mirror/rtic
1
0
Fork 0
mirror of https://github.com/rtic-rs/rtic.git synced 2024-11-25 21:19:35 +01:00
Code Issues Projects Releases Packages Wiki Activity

Update upstream

Browse source
This commit is contained in:
Roman Isaikin 2023-03-15 14:44:50 +01:00
commit a314de6d76
418 changed files with 15146 additions and 9595 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
.cargo/config → .cargo/config.toml
View file

@ -1,3 +1,6 @@
[alias]
xtask = "run --package xtask --"
[target.thumbv6m-none-eabi]
runner = "qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic -semihosting-config enable=on,target=native -kernel"

1
.gitattributes vendored Normal file
View file

@ -0,0 +1 @@
CHANGELOG.md merge=union

14
.github/dependabot.yml vendored Normal file
View file

@ -0,0 +1,14 @@
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
labels:
- "skip-changelog"
- package-ecosystem: "cargo"
directory: "/"
schedule:
interval: "weekly"
labels:
- "skip-changelog"

2
.github/workflows/audit.yaml vendored
View file

@ -6,7 +6,7 @@ jobs:
audit:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v1
- uses: actions/checkout@v3
- uses: actions-rs/audit-check@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}

1059
.github/workflows/build.yml vendored
View file

File diff suppressed because it is too large Load diff

73
.github/workflows/changelog.yml vendored Normal file
View file

@ -0,0 +1,73 @@
# Check that the changelog is updated for all changes.
#
# This is only run for PRs.
on:
pull_request:
# opened, reopened, synchronize are the default types for pull_request.
# labeled, unlabeled ensure this check is also run if a label is added or removed.
types: [opened, reopened, labeled, unlabeled, synchronize]
name: Changelog
jobs:
changelog:
name: Changelog
runs-on: ubuntu-latest
steps:
- name: Checkout sources
uses: actions/checkout@v3
- name: Check which component is modified
uses: dorny/paths-filter@v2
id: changes
with:
filters: |
rtic:
- 'rtic/**'
rtic-channel:
- 'rtic-channel/**'
rtic-time:
- 'rtic-time/**'
rtic-monotonics:
- 'rtic-monotonics/**'
- name: Check that changelog updated (rtic)
if: steps.changes.outputs.rtic == 'true'
uses: dangoslen/changelog-enforcer@v3
with:
changeLogPath: ./rtic/CHANGELOG.md
skipLabels: 'needs-changelog, skip-changelog'
missingUpdateErrorMessage: 'Please add a changelog entry in the rtic/CHANGELOG.md file.'
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Check that changelog updated (rtic-channel)
if: steps.changes.outputs.rtic-channel == 'true'
uses: dangoslen/changelog-enforcer@v3
with:
changeLogPath: ./rtic-channel/CHANGELOG.md
skipLabels: 'needs-changelog, skip-changelog'
missingUpdateErrorMessage: 'Please add a changelog entry in the rtic-channel/CHANGELOG.md file.'
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Check that changelog updated (rtic-time)
if: steps.changes.outputs.rtic-time == 'true'
uses: dangoslen/changelog-enforcer@v3
with:
changeLogPath: ./rtic-time/CHANGELOG.md
skipLabels: 'needs-changelog, skip-changelog'
missingUpdateErrorMessage: 'Please add a changelog entry in the rtic-time/CHANGELOG.md file.'
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Check that changelog updated (rtic-monotonics)
if: steps.changes.outputs.rtic-monotonics == 'true'
uses: dangoslen/changelog-enforcer@v3
with:
changeLogPath: ./rtic-monotonics/CHANGELOG.md
skipLabels: 'needs-changelog, skip-changelog'
missingUpdateErrorMessage: 'Please add a changelog entry in the rtic-monotonics/CHANGELOG.md file.'
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

44
.github/workflows/matrix-bot.yml vendored Normal file
View file

@ -0,0 +1,44 @@
name: Matrix bot
on:
pull_request_target:
types: [opened, closed]
jobs:
new-pr:
if: github.event.action == 'opened' && github.repository == 'rtic-rs/rtic'
runs-on: ubuntu-latest
continue-on-error: true
steps:
- name: send message
uses: s3krit/matrix-message-action@v0.0.3
with:
room_id: ${{ secrets.MATRIX_ROOM_ID }}
access_token: ${{ secrets.MATRIX_ACCESS_TOKEN }}
message: "New PR: [${{ github.event.pull_request.title }}](${{ github.event.pull_request.html_url }})"
server: "matrix.org"
merged-pr:
if: github.event.action == 'closed' && github.event.pull_request.merged == true && github.repository == 'rtic-rs/rtic'
runs-on: ubuntu-latest
continue-on-error: true
steps:
- name: send message
uses: s3krit/matrix-message-action@v0.0.3
with:
room_id: ${{ secrets.MATRIX_ROOM_ID }}
access_token: ${{ secrets.MATRIX_ACCESS_TOKEN }}
message: "PR merged: [${{ github.event.pull_request.title }}](${{ github.event.pull_request.html_url }})"
server: "matrix.org"
abandoned-pr:
if: github.event.action == 'closed' && github.event.pull_request.merged == false && github.repository == 'rtic-rs/rtic'
runs-on: ubuntu-latest
continue-on-error: true
steps:
- name: send message
uses: s3krit/matrix-message-action@v0.0.3
with:
room_id: ${{ secrets.MATRIX_ROOM_ID }}
access_token: ${{ secrets.MATRIX_ACCESS_TOKEN }}
message: "PR closed without merging: [${{ github.event.pull_request.title }}](${{ github.event.pull_request.html_url }})"
server: "matrix.org"

77
CONTRIBUTING.md
View file

@ -1,16 +1,83 @@
# Contributing
## New features
New features should go through the [RFC process][rfcs] before a Pull Request is made to this repository.
[rfcs](https://github.com/rtic-rs/rfcs)
## New features
New features should go through the [RFC process][rfcs] before creating a Pull Request to this repository.
[rfcs]: https://github.com/rtic-rs/rfcs
## Bugs
Report bugs by creating an issue in this repository.
## Pull Requests
## Pull Requests (PRs)
Please make pull requests against the master branch.
Always use rebase instead of merge when bringing in changes from master to your feature branch.
## Writing documentation
Documentation improvements are always welcome. The source for the book is in `book/` and API documentation is generated from the source code.
Documentation improvements are always welcome.
The source for the book is in `book/` and API documentation is generated from the source code.
## CI test preparation
Continuous Integration (CI) tests are run against all pull requests.
Please make sure that tests passes locally before submitting.
### Cargo format
```shell
> cargo fmt
```
### Example check
```shell
> cargo check --examples --target thumbv7m-none-eabi
```
and/or
```shell
> cargo check --examples --target thumbv6m-none-eabi
```
### Run tests with xtask
```shell
> cargo xtask --target all
```
Will execute `run` tests on your local `qemu` install.
(You may also pass a single target `--target thumbv6m-none-eabi/thumbv7m-none-eabi` during development).
#### Adding tests to xtask
If you have added further tests, you need to add the expected output in the `ci/expected` folder.
```shell
> cargo run --example <NAME> --target thumbv7m-none-eabi > ci/expected/<NAME>.run
```
### Internal tests
Run internal fail tests locally with:
```shell
> cargo test --tests
```
#### Adding tests to internal tests
If you have added fail tests or changed the expected behavior, the expected output needs to be updated (corresponding `.stderr` files).
Inspect the error output, when sure that `ACTUAL OUTPUT` is correct you can re-run the test as:
```shell
> TRYBUILD=overwrite cargo test --tests
```
This will update the expected output to match the `ACTUAL OUTPUT`.
Please check that the updated files are indeed correct to avoid regressions.

85
Cargo.toml
View file

@ -1,84 +1,18 @@
[package]
authors = [
"The Real-Time Interrupt-driven Concurrency developers",
"Jorge Aparicio <jorge@japaric.io>",
"Per Lindgren <per.lindgren@ltu.se>",
[workspace]
members = [
"rtic",
"rtic-sync",
"rtic-common",
"rtic-macros",
"rtic-monotonics",
"rtic-time",
"xtask",
]
categories = ["concurrency", "embedded", "no-std"]
description = "Real-Time Interrupt-driven Concurrency (RTIC): a concurrency framework for building real-time systems"
documentation = "https://rtic.rs/"
edition = "2018"
keywords = ["arm", "cortex-m"]
license = "MIT OR Apache-2.0"
name = "cortex-m-rtic"
readme = "README.md"
repository = "https://github.com/rtic-rs/cortex-m-rtic"
version = "0.6.0-alpha.5"
[lib]
name = "rtic"
[[example]]
name = "periodic"
required-features = ["__v7"]
[[example]]
name = "pool"
required-features = ["__v7"]
[[example]]
name = "schedule"
required-features = ["__v7"]
[[example]]
name = "t-schedule"
required-features = ["__v7"]
[[example]]
name = "double_schedule"
required-features = ["__v7"]
[dependencies]
cortex-m = "0.7.0"
cortex-m-rtic-macros = { path = "macros", version = "0.6.0-alpha.5" }
rtic-monotonic = "0.1.0-alpha.2"
rtic-core = "0.3.1"
heapless = "0.6.1"
bare-metal = "1.0.0"
generic-array = "0.14"
[dependencies.dwt-systick-monotonic]
version = "0.1.0-alpha.3"
optional = true
[build-dependencies]
version_check = "0.9"
[dev-dependencies]
lm3s6965 = "0.1.3"
cortex-m-semihosting = "0.3.3"
[dev-dependencies.panic-semihosting]
features = ["exit"]
version = "0.5.2"
[target.x86_64-unknown-linux-gnu.dev-dependencies]
trybuild = "1"
[features]
# used for testing this crate; do not use in applications
__v7 = ["dwt-systick-monotonic"]
[profile.release]
codegen-units = 1
lto = true
[workspace]
members = [
"macros",
]
# do not optimize proc-macro deps or build scripts
[profile.dev.build-override]
codegen-units = 16
@ -97,4 +31,3 @@ overflow-checks = false
[patch.crates-io]
lm3s6965 = { git = "https://github.com/japaric/lm3s6965" }
# embedded-time = { path = "../../embedded-time" }

44
README.md
View file

@ -1,13 +1,12 @@
# Real-Time Interrupt-driven Concurrency
> The hardware accelerated Rust RTOS
A concurrency framework for building real-time systems.
Formerly known as Real-Time For the Masses.
[![crates.io](https://img.shields.io/crates/v/cortex-m-rtic)](https://crates.io/crates/cortex-m-rtic)
[![docs.rs](https://docs.rs/cortex-m-rtic/badge.svg)](https://docs.rs/cortex-m-rtic)
[![crates.io](https://img.shields.io/crates/v/rtic)](https://crates.io/crates/rtic)
[![docs.rs](https://docs.rs/rtic/badge.svg)](https://docs.rs/rtic)
[![book](https://img.shields.io/badge/web-rtic.rs-red.svg?style=flat&label=book&colorB=d33847)](https://rtic.rs/)
[![rustc](https://img.shields.io/badge/rustc-1.36+-lightgray.svg)](https://github.com/rust-lang/rust/releases/tag/1.36.0)
[![matrix](https://img.shields.io/matrix/rtic:matrix.org)](https://matrix.to/#/#rtic:matrix.org)
[![Meeting notes](https://hackmd.io/badge.svg)](https://hackmd.io/@xmis9JvZT8Gvo9lOEKyZ4Q/SkBJKsjuH)
@ -25,7 +24,7 @@ Formerly known as Real-Time For the Masses.
- Support for prioritization of tasks and, thus, **preemptive multitasking**.
- **Efficient and data race free memory sharing** through fine grained *priority
- **Efficient and data race free memory sharing** through fine-grained *priority
based* critical sections [^1].
- **Deadlock free execution** guaranteed at compile time. This is a stronger
@ -43,27 +42,26 @@ Formerly known as Real-Time For the Masses.
- **All Cortex-M devices are fully supported**.
- This task model is amenable to known WCET (Worst Case Execution Time) analysis
and scheduling analysis techniques. (Though we haven't yet developed Rust
friendly tooling for that.)
## Requirements
- Rust 1.36.0+
- Applications must be written using the 2018 edition.
and scheduling analysis techniques.
## [User documentation](https://rtic.rs)
Documentation for the [development version](https://rtic.rs/dev).
## [API reference](https://rtic.rs/stable/api/)
## [Community provided examples repo][examples]
[examples]: https://github.com/rtic-rs/rtic-examples
## Chat
Join us and talk about RTIC in the [Matrix room][matrix-room].
Weekly meeting notes can be found over at [HackMD][hackmd]
Weekly meeting minutes can be found over at [RTIC HackMD][hackmd]
[matrix-room]: https://matrix.to/#/#rtic:matrix.org
[hackmd]: https://hackmd.io/@xmis9JvZT8Gvo9lOEKyZ4Q/SkBJKsjuH
[hackmd]: rtic.rs/meeting
## Contributing
@ -72,15 +70,25 @@ New features and big changes should go through the RFC process in the
[rfcs]: https://github.com/rtic-rs/rfcs
## Running tests locally
To check all `Run-pass tests` locally on your `thumbv6m-none-eabi` or `thumbv7m-none-eabi` target device, run
```console
$ cargo xtask --target <your target>
# ˆˆˆˆˆˆˆˆˆˆˆˆ
# e.g. thumbv7m-none-eabi
```
## Acknowledgments
This crate is based on the [Real-Time For the Masses language][rtfm-lang]
created by the Embedded Systems group at [Luleå University of Technology][ltu],
led by [Prof. Per Lindgren][per].
led by [Prof. Per Lindgren][perl].
[rtfm-lang]: http://www.rtfm-lang.org/
[ltu]: https://www.ltu.se/?l=en
[per]: https://www.ltu.se/staff/p/pln-1.11258?l=en
[perl]: https://www.ltu.se/staff/p/pln-1.11258?l=en
## References

6
README_ru.md
View file

@ -50,10 +50,16 @@
- Приложения должны быть написаны в редакции 2018.
## [Руководство пользователя](https://rtic.rs) - [(Версия в разработке)](https://rtic.rs/dev)
## [Документация пользователя](https://rtic.rs)
## [Справочник по API](https://rtic.rs/stable/api/)
## [Сборник примеров, предоставляемы сообществом][examples]
[examples]: https://github.com/rtic-rs/rtic-examples
## Чат
Присоединяйтесь к нам, чтобы говорить о RTIC [в Matrix-комнате][matrix-room].

2
book/.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
# Make sure that mdbook output in repo-root/book/<language>/book is ignored
*/book

17
book/en/book.toml
View file

@ -1,9 +1,22 @@
[book]
authors = ["Jorge Aparicio, Per Lindgren and The Real-Time Interrupt-driven Concurrency developers"]
authors = [
"The Real-Time Interrupt-driven Concurrency developers",
"Emil Fresk <emil.fresk@gmail.com>",
"Henrik Tjäder <henrik@tjaders.com>",
"Jorge Aparicio <jorge@japaric.io>",
"Per Lindgren <per.lindgren@ltu.se>",
]
multilingual = false
src = "src"
title = "Real-Time Interrupt-driven Concurrency"
[build]
create-missing = false
[preprocessor.mermaid]
command = "mdbook-mermaid"
[output.html]
git-repository-url = "https://github.com/rtic-rs/cortex-m-rtic"
git-repository-url = "https://github.com/rtic-rs/rtic"
git-repository-icon = "fa-github"
additional-js = ["mermaid.min.js", "mermaid-init.js"]

1
book/en/mermaid-init.js Normal file
View file

@ -0,0 +1 @@
mermaid.initialize({startOnLoad:true});

1282
book/en/mermaid.min.js vendored Normal file
View file

File diff suppressed because one or more lines are too long

39
book/en/src/SUMMARY.md
View file

@ -3,18 +3,32 @@
[Preface](./preface.md)
- [RTIC by example](./by-example.md)
- [The `app` attribute](./by-example/app.md)
- [The `app`](./by-example/app.md)
- [Hardware tasks & `pend`](./by-example/hardware_tasks.md)
- [Software tasks & `spawn`](./by-example/software_tasks.md)
- [Resources](./by-example/resources.md)
- [Software tasks](./by-example/tasks.md)
- [Timer queue](./by-example/timer-queue.md)
- [Types, Send and Sync](./by-example/types-send-sync.md)
- [Starting a new project](./by-example/new.md)
- [Tips & tricks](./by-example/tips.md)
- [Migration Guides](./migration.md)
- [v0.5.x to v0.6.x](./migration/migration_v5.md)
- [The init task](./by-example/app_init.md)
- [The idle task](./by-example/app_idle.md)
- [Channel based communication](./by-example/channel.md)
- [Delay and Timeout](./by-example/delay.md)
- [Starting a new project](./by-example/starting_a_project.md)
- [The minimal app](./by-example/app_minimal.md)
- [Tips & Tricks](./by-example/tips.md)
- [Implementing Monotonic](./by-example/tips_monotonic_impl.md)
- [Resource de-structure-ing](./by-example/tips_destructureing.md)
- [Avoid copies when message passing](./by-example/tips_indirection.md)
- [`'static` super-powers](./by-example/tips_static_lifetimes.md)
- [Inspecting generated code](./by-example/tips_view_code.md)
<!-- - [Running tasks from RAM](./by-example/tips_from_ram.md) -->
<!-- - [`#[cfg(..)]` support](./by-example/tips.md) -->
- [RTIC vs. the world](./rtic_vs.md)
- [Awesome RTIC examples](./awesome_rtic.md)
<!-- - [Migration Guides](./migration.md)
- [v0.5.x to v1.0.x](./migration/migration_v5.md)
- [v0.4.x to v0.5.x](./migration/migration_v4.md)
- [RTFM to RTIC](./migration/migration_rtic.md)
- [RTFM to RTIC](./migration/migration_rtic.md) -->
- [Under the hood](./internals.md)
- [Cortex-M architectures](./internals/targets.md)
<!--- [Interrupt configuration](./internals/interrupt-configuration.md)-->
<!--- [Non-reentrancy](./internals/non-reentrancy.md)-->
<!--- [Access control](./internals/access.md)-->
@ -23,3 +37,10 @@
<!--- [Ceiling analysis](./internals/ceilings.md)-->
<!--- [Software tasks](./internals/tasks.md)-->
<!--- [Timer queue](./internals/timer-queue.md)-->
<!-- - [Defining tasks](./by-example/app_task.md) -->
<!-- - [Software tasks & `spawn`](./by-example/software_tasks.md)
- [Message passing & `capacity`](./by-example/message_passing.md)
- [Task priorities](./by-example/app_priorities.md)
- [Monotonic & `spawn_{at/after}`](./by-example/monotonic.md)
-->

8
book/en/src/awesome_rtic.md Normal file
View file

@ -0,0 +1,8 @@
# Awesome RTIC examples
See the [`rtic-rs/rtic-examples`][rticexamples] repository for community
provided complete examples.
Pull-requests to this repo are welcome!
[rticexamples]: https://github.com/rtic-rs/rtic-examples

40
book/en/src/by-example.md
View file

@ -1,24 +1,40 @@
# RTIC by example
This part of the book introduces the Real-Time Interrupt-driven Concurrency (RTIC) framework
to new users by walking them through examples of increasing complexity.
This part of the book introduces the RTIC framework to new users by walking them through examples of increasing complexity.
All examples in this part of the book can be found in the GitHub [repository] of
the project, and most of the examples can be run on QEMU so no special hardware
is required to follow along.
All examples in this part of the book are accessible at the
[GitHub repository][repoexamples].
The examples are runnable on QEMU (emulating a Cortex M3 target),
thus no special hardware required to follow along.
[repository]: https://github.com/rtic-rs/cortex-m-rtic
[repoexamples]: https://github.com/rtic-rs/rtic/tree/master/examples
To run the examples on your computer you'll need the `qemu-system-arm`
program. Check [the embedded Rust book] for instructions on how to set up an
## Running an example
To run the examples with QEMU you will need the `qemu-system-arm` program.
Check [the embedded Rust book] for instructions on how to set up an
embedded development environment that includes QEMU.
[the embedded Rust book]: https://rust-embedded.github.io/book/intro/install.html
## Real World Examples
To run the examples found in `examples/` locally, cargo needs a supported `target` and
either `--examples` (run all examples) or `--example NAME` to run a specific example.
The following are examples of RTFM being used in real world projects.
Assuming dependencies in place, running:
### RTFM V0.4.2
``` console
$ cargo run --target thumbv7m-none-eabi --example locals
```
- [etrombly/sandbox](https://github.com/etrombly/sandbox/tree/41d423bcdd0d8e42fd46b79771400a8ca349af55). A hardware zen garden that draws patterns in sand. Patterns are sent over serial using G-code.
Yields this output:
``` console
{{#include ../../../rtic/ci/expected/locals.run}}
```
> **NOTE**: You can choose target device by passing a target
> triple to cargo (e.g. `cargo run --example init --target thumbv7m-none-eabi`) or
> configure a default target in `.cargo/config.toml`.
>
> For running the examples, we (typically) use a Cortex M3 emulated in QEMU, so the target is `thumbv7m-none-eabi`.
> Since the M3 architecture is backwards compatible to the M0/M0+ architecture, you may also use the `thumbv6m-none-eabi`, in case you want to inspect generated assembly code for the M0/M0+ architecture.

160
book/en/src/by-example/app.md
View file

@ -1,156 +1,32 @@
# The `app` attribute
# The `#[app]` attribute and an RTIC application
This is the smallest possible RTIC application:
## Requirements on the `app` attribute
``` rust
{{#include ../../../../examples/smallest.rs}}
```
All RTIC applications use the [`app`] attribute (`#[app(..)]`). This attribute only applies to a `mod`-item containing the RTIC application. The `app` attribute has a mandatory `device` argument that takes a *path* as a value. This must be a full path pointing to a *peripheral access crate* (PAC) generated using [`svd2rust`] **v0.14.x** or newer.
All RTIC applications use the [`app`] attribute (`#[app(..)]`). This attribute
must be applied to a `mod`-item. The `app` attribute has a mandatory `device`
argument that takes a *path* as a value. This must be a full path pointing to a
*peripheral access crate* (PAC) generated using [`svd2rust`] **v0.14.x** or
newer. More details can be found in the [Starting a new project](./new.md)
section.
The `app` attribute will expand into a suitable entry point and thus replaces the use of the [`cortex_m_rt::entry`] attribute.
The `app` attribute will expand into a suitable entry point so it's not required
to use the [`cortex_m_rt::entry`] attribute.
[`app`]: ../../../api/cortex_m_rtic_macros/attr.app.html
[`app`]: ../../../api/rtic_macros/attr.app.html
[`svd2rust`]: https://crates.io/crates/svd2rust
[`cortex_m_rt::entry`]: ../../../api/cortex_m_rt_macros/attr.entry.html
[`cortex_m_rt::entry`]: https://docs.rs/cortex-m-rt-macros/latest/cortex_m_rt_macros/attr.entry.html
## `init`
## Structure and zero-cost concurrency
Within the `app` module the attribute expects to find an initialization
function marked with the `init` attribute. This function must have
signature `fn(init::Context) -> (init::LateResources, init::Monotonics)`.
An RTIC `app` is an executable system model for single-core applications, declaring a set of `local` and `shared` resources operated on by a set of `init`, `idle`, *hardware* and *software* tasks. In short the `init` task runs before any other task returning the set of `local` and `shared` resources. Tasks run preemptively based on their associated static priority, `idle` has the lowest priority (and can be used for background work, and/or to put the system to sleep until woken by some event). Hardware tasks are bound to underlying hardware interrupts, while software tasks are scheduled by asynchronous executors (one for each software task priority).
This initialization function will be the first part of the application to run.
The `init` function will run *with interrupts disabled* and has exclusive access
to Cortex-M where the `bare_metal::CriticalSection` token is available as `cs`.
And optionally, device specific peripherals through the `core` and `device` fields
of `init::Context`.
At compile time the task/resource model is analyzed under the Stack Resource Policy (SRP) and executable code generated with the following outstanding properties:
`static mut` variables declared at the beginning of `init` will be transformed
into `&'static mut` references that are safe to access. Notice, this feature may be deprecated in next release, see `task_local` resources.
- guaranteed race-free resource access and deadlock-free execution on a single-shared stack
- hardware task scheduling is performed directly by the hardware, and
- software task scheduling is performed by auto generated async executors tailored to the application.
[`rtic::Peripherals`]: ../../api/rtic/struct.Peripherals.html
Overall, the generated code infers no additional overhead in comparison to a hand-written implementation, thus in Rust terms RTIC offers a zero-cost abstraction to concurrency.
The example below shows the types of the `core`, `device` and `cs` fields, and
showcases safe access to a `static mut` variable. The `device` field is only
available when the `peripherals` argument is set to `true` (default). In the rare case you want to implement an ultra-slim application you can explicitly set `peripherals` to `false`.
## An RTIC application example
To give a flavour of RTIC, the following example contains commonly used features.
In the following sections we will go through each feature in detail.
``` rust
{{#include ../../../../examples/init.rs}}
{{#include ../../../../rtic/examples/common.rs}}
```
Running the example will print `init` to the console and then exit the QEMU
process.
``` console
$ cargo run --example init
{{#include ../../../../ci/expected/init.run}}
```
## `idle`
A function marked with the `idle` attribute can optionally appear in the
module. This function is used as the special *idle task* and must have
signature `fn(idle::Context) - > !`.
When present, the runtime will execute the `idle` task after `init`. Unlike
`init`, `idle` will run *with interrupts enabled* and it's not allowed to return
so it must run forever.
When no `idle` function is declared, the runtime sets the [SLEEPONEXIT] bit and
then sends the microcontroller to sleep after running `init`.
[SLEEPONEXIT]: https://developer.arm.com/docs/100737/0100/power-management/sleep-mode/sleep-on-exit-bit
Like in `init`, `static mut` variables will be transformed into `&'static mut`
references that are safe to access. Notice, this feature may be deprecated in the next release, see `task_local` resources.
The example below shows that `idle` runs after `init`.
**Note:** The `loop {}` in idle cannot be empty as this will crash the microcontroller due to
LLVM compiling empty loops to an `UDF` instruction in release mode. To avoid UB, the loop needs to imply a "side-effect" by inserting an assembly instruction (e.g., `WFI`) or a `continue`.
``` rust
{{#include ../../../../examples/idle.rs}}
```
``` console
$ cargo run --example idle
{{#include ../../../../ci/expected/idle.run}}
```
## Hardware tasks
To declare interrupt handlers the framework provides a `#[task]` attribute that
can be attached to functions. This attribute takes a `binds` argument whose
value is the name of the interrupt to which the handler will be bound to; the
function adorned with this attribute becomes the interrupt handler. Within the
framework these type of tasks are referred to as *hardware* tasks, because they
start executing in reaction to a hardware event.
The example below demonstrates the use of the `#[task]` attribute to declare an
interrupt handler. Like in the case of `#[init]` and `#[idle]` local `static
mut` variables are safe to use within a hardware task.
``` rust
{{#include ../../../../examples/hardware.rs}}
```
``` console
$ cargo run --example hardware
{{#include ../../../../ci/expected/hardware.run}}
```
So far all the RTIC applications we have seen look no different than the
applications one can write using only the `cortex-m-rt` crate. From this point
we start introducing features unique to RTIC.
## Priorities
The static priority of each handler can be declared in the `task` attribute
using the `priority` argument. Tasks can have priorities in the range `1..=(1 <<
NVIC_PRIO_BITS)` where `NVIC_PRIO_BITS` is a constant defined in the `device`
crate. When the `priority` argument is omitted, the priority is assumed to be
`1`. The `idle` task has a non-configurable static priority of `0`, the lowest priority.
> A higher number means a higher priority in RTIC, which is the opposite from what
> Cortex-M does in the NVIC peripheral.
> Explicitly, this means that number `10` has a **higher** priority than number `9`.
When several tasks are ready to be executed the one with highest static
priority will be executed first. Task prioritization can be observed in the
following scenario: an interrupt signal arrives during the execution of a low
priority task; the signal puts the higher priority task in the pending state.
The difference in priority results in the higher priority task preempting the
lower priority one: the execution of the lower priority task is suspended and
the higher priority task is executed to completion. Once the higher priority
task has terminated the lower priority task is resumed.
The following example showcases the priority based scheduling of tasks.
``` rust
{{#include ../../../../examples/preempt.rs}}
```
``` console
$ cargo run --example preempt
{{#include ../../../../ci/expected/preempt.run}}
```
Note that the task `gpiob` does *not* preempt task `gpioc` because its priority
is the *same* as `gpioc`'s. However, once `gpioc` returns, the execution of
task `gpiob` is prioritized over `gpioa` due to its higher priority. `gpioa`
is resumed only after `gpiob` returns.
One more note about priorities: choosing a priority higher than what the device
supports (that is `1 << NVIC_PRIO_BITS`) will result in a compile error. Due to
limitations in the language, the error message is currently far from helpful: it
will say something along the lines of "evaluation of constant value failed" and
the span of the error will *not* point out to the problematic interrupt value --
we are sorry about this!

53
book/en/src/by-example/app_idle.md Normal file
View file

@ -0,0 +1,53 @@
# The background task `#[idle]`
A function marked with the `idle` attribute can optionally appear in the module. This becomes the special *idle task* and must have signature `fn(idle::Context) -> !`.
When present, the runtime will execute the `idle` task after `init`. Unlike `init`, `idle` will run *with interrupts enabled* and must never return, as the `-> !` function signature indicates.
[The Rust type `!` means “never”][nevertype].
[nevertype]: https://doc.rust-lang.org/core/primitive.never.html
Like in `init`, locally declared resources will have `'static` lifetimes that are safe to access.
The example below shows that `idle` runs after `init`.
``` rust
{{#include ../../../../rtic/examples/idle.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example idle
```
``` console
{{#include ../../../../rtic/ci/expected/idle.run}}
```
By default, the RTIC `idle` task does not try to optimize for any specific targets.
A common useful optimization is to enable the [SLEEPONEXIT] and allow the MCU to enter sleep when reaching `idle`.
>**Caution**: some hardware unless configured disables the debug unit during sleep mode.
>
>Consult your hardware specific documentation as this is outside the scope of RTIC.
The following example shows how to enable sleep by setting the
[`SLEEPONEXIT`][SLEEPONEXIT] and providing a custom `idle` task replacing the default [`nop()`][NOP] with [`wfi()`][WFI].
[SLEEPONEXIT]: https://developer.arm.com/docs/100737/0100/power-management/sleep-mode/sleep-on-exit-bit
[WFI]: https://developer.arm.com/documentation/dui0662/b/The-Cortex-M0--Instruction-Set/Miscellaneous-instructions/WFI
[NOP]: https://developer.arm.com/documentation/dui0662/b/The-Cortex-M0--Instruction-Set/Miscellaneous-instructions/NOP
``` rust
{{#include ../../../../rtic/examples/idle-wfi.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example idle-wfi
```
``` console
{{#include ../../../../rtic/ci/expected/idle-wfi.run}}
```
> **Notice**: The `idle` task cannot be used together with *software* tasks running at priority zero. The reason is that `idle` is running as a non-returning Rust function at priority zero. Thus there would be no way for an executor at priority zero to give control to *software* tasks at the same priority.

31
book/en/src/by-example/app_init.md Normal file
View file

@ -0,0 +1,31 @@
# App initialization and the `#[init]` task
An RTIC application requires an `init` task setting up the system. The corresponding `init` function must have the
signature `fn(init::Context) -> (Shared, Local)`, where `Shared` and `Local` are resource structures defined by the user.
The `init` task executes after system reset, [after an optionally defined `pre-init` code section][pre-init] and an always occurring internal RTIC initialization. [pre-init]: https://docs.rs/cortex-m-rt/latest/cortex_m_rt/attr.pre_init.html
The `init` and optional `pre-init` tasks runs *with interrupts disabled* and have exclusive access to Cortex-M (the `bare_metal::CriticalSection` token is available as `cs`).
Device specific peripherals are available through the `core` and `device` fields of `init::Context`.
## Example
The example below shows the types of the `core`, `device` and `cs` fields, and showcases the use of a `local` variable with `'static` lifetime. Such variables can be delegated from the `init` task to other tasks of the RTIC application.
The `device` field is only available when the `peripherals` argument is set to the default value `true`.
In the rare case you want to implement an ultra-slim application you can explicitly set `peripherals` to `false`.
``` rust
{{#include ../../../../rtic/examples/init.rs}}
```
Running the example will print `init` to the console and then exit the QEMU process.
``` console
$ cargo run --target thumbv7m-none-eabi --example init
```
``` console
{{#include ../../../../rtic/ci/expected/init.run}}
```

24
book/en/src/by-example/app_minimal.md Normal file
View file

@ -0,0 +1,24 @@
# The minimal app
This is the smallest possible RTIC application:
``` rust
{{#include ../../../../rtic/examples/smallest.rs}}
```
RTIC is designed with resource efficiency in mind. RTIC itself does not rely on any dynamic memory allocation, thus RAM requirement is dependent only on the application. The flash memory footprint is below 1kB including the interrupt vector table.
For a minimal example you can expect something like:
``` console
$ cargo size --example smallest --target thumbv7m-none-eabi --release
```
``` console
Finished release [optimized] target(s) in 0.07s
text data bss dec hex filename
924 0 0 924 39c smallest
```
<!-- ---
Technically, RTIC will generate a statically allocated future for each *software* task (holding the execution context, including the `Context` struct and stack allocated variables). Futures associated to the same static priority will share an asynchronous stack during execution. -->

62
book/en/src/by-example/app_priorities.md Normal file
View file

@ -0,0 +1,62 @@
# Task priorities
## Priorities
The `priority` argument declares the static priority of each `task`.
For Cortex-M, tasks can have priorities in the range `1..=(1 << NVIC_PRIO_BITS)` where `NVIC_PRIO_BITS` is a constant defined in the `device` crate.
Omitting the `priority` argument the task priority defaults to `1`. The `idle` task has a non-configurable static priority of `0`, the lowest priority.
> A higher number means a higher priority in RTIC, which is the opposite from what
> Cortex-M does in the NVIC peripheral.
> Explicitly, this means that number `10` has a **higher** priority than number `9`.
The highest static priority task takes precedence when more than one task are ready to execute.
The following scenario demonstrates task prioritization:
Spawning a higher priority task A during execution of a lower priority task B suspends task B. Task A has higher priority thus preempting task B which gets suspended until task A completes execution. Thus, when task A completes task B resumes execution.
```text
Task Priority
┌────────────────────────────────────────────────────────┐
│ │
│ │
3 │ Preempts │
2 │ A─────────► │
1 │ B─────────► - - - - B────────► │
0 │Idle┌─────► Resumes ┌──────────► │
├────┴──────────────────────────────────┴────────────────┤
│ │
└────────────────────────────────────────────────────────┘Time
```
The following example showcases the priority based scheduling of tasks:
``` rust
{{#include ../../../../rtic/examples/preempt.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example preempt
{{#include ../../../../rtic/ci/expected/preempt.run}}
```
Note that the task `bar` does *not* preempt task `baz` because its priority is the *same* as `baz`'s. The higher priority task `bar` runs before `foo` when `baz`returns. When `bar` returns `foo` can resume.
One more note about priorities: choosing a priority higher than what the device supports will result in a compilation error. The error is cryptic due to limitations in the Rust language, if `priority = 9` for task `uart0_interrupt` in `example/common.rs` this looks like:
The error is cryptic due to limitations in the Rust language if `priority = 9` for task `uart0_interrupt` in `example/common.rs` this looks like:
```text
error[E0080]: evaluation of constant value failed
--> examples/common.rs:10:1
|
10 | #[rtic::app(device = lm3s6965, dispatchers = [SSI0, QEI0])]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ attempt to compute `8_usize - 9_usize`, which would overflow
|
= note: this error originates in the attribute macro `rtic::app` (in Nightly builds, run with -Z macro-backtrace for more info)
```
The error message incorrectly points to the starting point of the macro, but at least the value subtracted (in this case 9) will suggest which task causes the error.

23
book/en/src/by-example/app_task.md Normal file
View file

@ -0,0 +1,23 @@
<!-- Should probably be removed -->
# Defining tasks with `#[task]`
Tasks, defined with `#[task]`, are the main mechanism of getting work done in RTIC.
Tasks can
* Be spawned (now or in the future, also by themselves)
* Receive messages (passing messages between tasks)
* Be prioritized, allowing preemptive multitasking
* Optionally bind to a hardware interrupt
RTIC makes a distinction between “software tasks” and “hardware tasks”.
*Hardware tasks* are tasks that are bound to a specific interrupt vector in the MCU while software tasks are not.
This means that if a hardware task is bound to, lets say, a UART RX interrupt, the task will be run every
time that interrupt triggers, usually when a character is received.
*Software tasks* are explicitly spawned in a task, either immediately or using the Monotonic timer mechanism.
In the coming pages we will explore both tasks and the different options available.

126
book/en/src/by-example/channel.md Normal file
View file

@ -0,0 +1,126 @@
# Communication over channels.
Channels can be used to communicate data between running *software* tasks. The channel is essentially a wait queue, allowing tasks with multiple producers and a single receiver. A channel is constructed in the `init` task and backed by statically allocated memory. Send and receive endpoints are distributed to *software* tasks:
``` rust
...
const CAPACITY: usize = 5;
#[init]
fn init(_: init::Context) -> (Shared, Local) {
let (s, r) = make_channel!(u32, CAPACITY);
receiver::spawn(r).unwrap();
sender1::spawn(s.clone()).unwrap();
sender2::spawn(s.clone()).unwrap();
...
```
In this case the channel holds data of `u32` type with a capacity of 5 elements.
## Sending data
The `send` method post a message on the channel as shown below:
``` rust
#[task]
async fn sender1(_c: sender1::Context, mut sender: Sender<'static, u32, CAPACITY>) {
hprintln!("Sender 1 sending: 1");
sender.send(1).await.unwrap();
}
```
## Receiving data
The receiver can `await` incoming messages:
``` rust
#[task]
async fn receiver(_c: receiver::Context, mut receiver: Receiver<'static, u32, CAPACITY>) {
while let Ok(val) = receiver.recv().await {
hprintln!("Receiver got: {}", val);
...
}
}
```
Channels are implemented using a small (global) *Critical Section* (CS) for protection against race-conditions. The user must provide an CS implementation. Compiling the examples given the `--features test-critical-section` gives one possible implementation.
For a complete example:
``` rust
{{#include ../../../../rtic/examples/async-channel.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example async-channel --features test-critical-section
```
``` console
{{#include ../../../../rtic/ci/expected/async-channel.run}}
```
Also sender endpoint can be awaited. In case the channel capacity has not yet been reached, `await`-ing the sender can progress immediately, while in the case the capacity is reached, the sender is blocked until there is free space in the queue. In this way data is never lost.
In the following example the `CAPACITY` has been reduced to 1, forcing sender tasks to wait until the data in the channel has been received.
``` rust
{{#include ../../../../rtic/examples/async-channel-done.rs}}
```
Looking at the output, we find that `Sender 2` will wait until the data sent by `Sender 1` as been received.
> **NOTICE** *Software* tasks at the same priority are executed asynchronously to each other, thus **NO** strict order can be assumed. (The presented order here applies only to the current implementation, and may change between RTIC framework releases.)
``` console
$ cargo run --target thumbv7m-none-eabi --example async-channel-done --features test-critical-section
{{#include ../../../../rtic/ci/expected/async-channel-done.run}}
```
## Error handling
In case all senders have been dropped `await`-ing on an empty receiver channel results in an error. This allows to gracefully implement different types of shutdown operations.
``` rust
{{#include ../../../../rtic/examples/async-channel-no-sender.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example async-channel-no-sender --features test-critical-section
```
``` console
{{#include ../../../../rtic/ci/expected/async-channel-no-sender.run}}
```
Similarly, `await`-ing on a send channel results in an error in case the receiver has been dropped. This allows to gracefully implement application level error handling.
The resulting error returns the data back to the sender, allowing the sender to take appropriate action (e.g., storing the data to later retry sending it).
``` rust
{{#include ../../../../rtic/examples/async-channel-no-receiver.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example async-channel-no-receiver --features test-critical-section
```
``` console
{{#include ../../../../rtic/ci/expected/async-channel-no-receiver.run}}
```
## Try API
In cases you wish the sender to proceed even in case the channel is full. To that end, a `try_send` API is provided.
``` rust
{{#include ../../../../rtic/examples/async-channel-try.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example async-channel-try --features test-critical-section
```
``` console
{{#include ../../../../rtic/ci/expected/async-channel-try.run}}
```

127
book/en/src/by-example/delay.md Normal file
View file

@ -0,0 +1,127 @@
# Tasks with delay
A convenient way to express *miniminal* timing requirements is by means of delaying progression.
This can be achieved by instantiating a monotonic timer:
``` rust
...
rtic_monotonics::make_systick_handler!();
#[init]
fn init(cx: init::Context) -> (Shared, Local) {
hprintln!("init");
Systick::start(cx.core.SYST, 12_000_000);
...
```
A *software* task can `await` the delay to expire:
``` rust
#[task]
async fn foo(_cx: foo::Context) {
...
Systick::delay(100.millis()).await;
...
}
```
Technically, the timer queue is implemented as a list based priority queue, where list-nodes are statically allocated as part of the underlying task `Future`. Thus, the timer queue is infallible at run-time (its size and allocation is determined at compile time).
Similarly the channels implementation, the timer-queue implementation relies on a global *Critical Section* (CS) for race protection. For the examples a CS implementation is provided by adding `--features test-critical-section` to the build options.
For a complete example:
``` rust
{{#include ../../../../rtic/examples/async-delay.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example async-delay --features test-critical-section
```
``` console
{{#include ../../../../rtic/ci/expected/async-delay.run}}
```
## Timeout
Rust `Futures` (underlying Rust `async`/`await`) are composable. This makes it possible to `select` in between `Futures` that have completed.
A common use case is transactions with associated timeout. In the examples shown below, we introduce a fake HAL device which performs some transaction. We have modelled the time it takes based on the input parameter (`n`) as `350ms + n * 100ms)`.
Using the `select_biased` macro from the `futures` crate it may look like this:
``` rust
// Call hal with short relative timeout using `select_biased`
select_biased! {
v = hal_get(1).fuse() => hprintln!("hal returned {}", v),
_ = Systick::delay(200.millis()).fuse() => hprintln!("timeout", ), // this will finish first
}
```
Assuming the `hal_get` will take 450ms to finish, a short timeout of 200ms will expire.
``` rust
// Call hal with long relative timeout using `select_biased`
select_biased! {
v = hal_get(1).fuse() => hprintln!("hal returned {}", v), // hal finish first
_ = Systick::delay(1000.millis()).fuse() => hprintln!("timeout", ),
}
```
By extending the timeout to 1000ms, the `hal_get` will finish first.
Using `select_biased` any number of futures can be combined, so its very powerful. However, as the timeout pattern is frequently used, it is directly supported by the RTIC [rtc-monotonics] and [rtic-time] crates. The second example from above using `timeout_after`:
``` rust
// Call hal with long relative timeout using monotonic `timeout_after`
match Systick::timeout_after(1000.millis(), hal_get(1)).await {
Ok(v) => hprintln!("hal returned {}", v),
_ => hprintln!("timeout"),
}
```
In cases you want exact control over time without drift. For this purpose we can use exact points in time using `Instance`, and spans of time using `Duration`. Operations on the `Instance` and `Duration` types are given by the [fugit] crate.
[fugit]: https://crates.io/crates/fugit
``` rust
// get the current time instance
let mut instant = Systick::now();
// do this 3 times
for n in 0..3 {
// absolute point in time without drift
instant += 1000.millis();
Systick::delay_until(instant).await;
// absolute point it time for timeout
let timeout = instant + 500.millis();
hprintln!("now is {:?}, timeout at {:?}", Systick::now(), timeout);
match Systick::timeout_at(timeout, hal_get(n)).await {
Ok(v) => hprintln!("hal returned {} at time {:?}", v, Systick::now()),
_ => hprintln!("timeout"),
}
}
```
`instant = Systick::now()` gives the baseline (i.e., the absolute current point in time). We want to call `hal_get` after 1000ms relative to this absolute point in time. This can be accomplished by `Systick::delay_until(instant).await;`. We define the absolute point in time for the `timeout`, and call `Systick::timeout_at(timeout, hal_get(n)).await`. For the first loop iteration `n == 0`, and the `hal_get` will take 350ms (and finishes before the timeout). For the second iteration `n == 1`, and `hal_get` will take 450ms (and again succeeds to finish before the timeout). For the third iteration `n == 2` (`hal_get` will take 5500ms to finish). In this case we will run into a timeout.
The complete example:
``` rust
{{#include ../../../../rtic/examples/async-timeout.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example async-timeout --features test-critical-section
```
``` console
{{#include ../../../../rtic/ci/expected/async-timeout.run}}
```

32
book/en/src/by-example/hardware_tasks.md Normal file
View file

@ -0,0 +1,32 @@
# Hardware tasks
At its core RTIC is using a hardware interrupt controller ([ARM NVIC on cortex-m][NVIC]) to schedule and start execution of tasks. All tasks except `pre-init`, `#[init]` and `#[idle]` run as interrupt handlers.
Hardware tasks are explicitly bound to interrupt handlers.
To bind a task to an interrupt, use the `#[task]` attribute argument `binds = InterruptName`. This task then becomes the interrupt handler for this hardware interrupt vector.
All tasks bound to an explicit interrupt are called *hardware tasks* since they start execution in reaction to a hardware event.
Specifying a non-existing interrupt name will cause a compilation error. The interrupt names are commonly defined by [PAC or HAL][pacorhal] crates.
Any available interrupt vector should work. Specific devices may bind specific interrupt priorities to specific interrupt vectors outside user code control. See for example the [nRF “softdevice”](https://github.com/rtic-rs/rtic/issues/434).
Beware of using interrupt vectors that are used internally by hardware features; RTIC is unaware of such hardware specific details.
[pacorhal]: https://docs.rust-embedded.org/book/start/registers.html
[NVIC]: https://developer.arm.com/documentation/100166/0001/Nested-Vectored-Interrupt-Controller/NVIC-functional-description/NVIC-interrupts
The example below demonstrates the use of the `#[task(binds = InterruptName)]` attribute to declare a hardware task bound to an interrupt handler.
``` rust
{{#include ../../../../rtic/examples/hardware.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example hardware
```
``` console
{{#include ../../../../rtic/ci/expected/hardware.run}}
```

20
book/en/src/by-example/message_passing.md Normal file
View file

@ -0,0 +1,20 @@
# Message passing & capacity
Software tasks support message passing, this means that software tasks can be spawned
with an argument: `foo::spawn(1)` which will run the task `foo` with the argument `1`.
Capacity sets the size of the spawn queue for the task, if not specified capacity defaults to 1.
In the example below, the capacity of task `foo` is `3`, allowing three simultaneous
pending spawns of `foo`. Exceeding this capacity is an `Error`.
The number of arguments to a task is not limited:
``` rust
{{#include ../../../../examples/message_passing.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example message_passing
{{#include ../../../../ci/expected/message_passing.run}}
```

64
book/en/src/by-example/monotonic.md Normal file
View file

@ -0,0 +1,64 @@
# Monotonic & spawn_{at/after}
The understanding of time is an important concept in embedded systems, and to be able to run tasks
based on time is essential. The framework provides the static methods
`task::spawn_after(/* duration */)` and `task::spawn_at(/* specific time instant */)`.
`spawn_after` is more commonly used, but in cases where it's needed to have spawns happen
without drift or to a fixed baseline `spawn_at` is available.
The `#[monotonic]` attribute, applied to a type alias definition, exists to support this.
This type alias must point to a type which implements the [`rtic_monotonic::Monotonic`] trait.
This is generally some timer which handles the timing of the system.
One or more monotonics can coexist in the same system, for example a slow timer that wakes the
system from sleep and another which purpose is for fine grained scheduling while the
system is awake.
[`rtic_monotonic::Monotonic`]: https://docs.rs/rtic-monotonic
The attribute has one required parameter and two optional parameters, `binds`, `default` and
`priority` respectively.
The required parameter, `binds = InterruptName`, associates an interrupt vector to the timer's
interrupt, while `default = true` enables a shorthand API when spawning and accessing
time (`monotonics::now()` vs `monotonics::MyMono::now()`), and `priority` sets the priority
of the interrupt vector.
> The default `priority` is the **maximum priority** of the system.
> If your system has a high priority task with tight scheduling requirements,
> it might be desirable to demote the `monotonic` task to a lower priority
> to reduce scheduling jitter for the high priority task.
> This however might introduce jitter and delays into scheduling via the `monotonic`,
> making it a trade-off.
The monotonics are initialized in `#[init]` and returned within the `init::Monotonic( ... )` tuple.
This activates the monotonics making it possible to use them.
See the following example:
``` rust
{{#include ../../../../examples/schedule.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example schedule
{{#include ../../../../ci/expected/schedule.run}}
```
A key requirement of a Monotonic is that it must deal gracefully with
hardware timer overruns.
## Canceling or rescheduling a scheduled task
Tasks spawned using `task::spawn_after` and `task::spawn_at` returns a `SpawnHandle`,
which allows canceling or rescheduling of the task scheduled to run in the future.
If `cancel` or `reschedule_at`/`reschedule_after` returns an `Err` it means that the operation was
too late and that the task is already sent for execution. The following example shows this in action:
``` rust
{{#include ../../../../examples/cancel-reschedule.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example cancel-reschedule
{{#include ../../../../ci/expected/cancel-reschedule.run}}
```

84
book/en/src/by-example/new.md
View file

@ -1,84 +0,0 @@
# Starting a new project
Now that you have learned about the main features of the RTIC framework you can
try it out on your hardware by following these instructions.
1. Instantiate the [`cortex-m-quickstart`] template.
[`cortex-m-quickstart`]: https://github.com/rust-embedded/cortex-m-quickstart#cortex-m-quickstart
``` console
$ # for example using `cargo-generate`
$ cargo generate \
--git https://github.com/rust-embedded/cortex-m-quickstart \
--name app
$ # follow the rest of the instructions
```
2. Add a peripheral access crate (PAC) that was generated using [`svd2rust`]
**v0.14.x**, or a board support crate that depends on one such PAC as a
dependency. Make sure that the `rt` feature of the crate is enabled.
[`svd2rust`]: https://crates.io/crates/svd2rust
In this example, I'll use the [`lm3s6965`] device crate. This device crate
doesn't have an `rt` Cargo feature; that feature is always enabled.
[`lm3s6965`]: https://crates.io/crates/lm3s6965
This device crate provides a linker script with the memory layout of the target
device so `memory.x` and `build.rs` need to be removed.
``` console
$ cargo add lm3s6965 --vers 0.1.3
$ rm memory.x build.rs
```
3. Add the `cortex-m-rtic` crate as a dependency.
``` console
$ cargo add cortex-m-rtic --allow-prerelease
```
4. Write your RTIC application.
Here I'll use the `init` example from the `cortex-m-rtic` crate.
The examples are found in the `examples` folder, and the contents
of `init.rs` is shown here:
``` console
{{#include ../../../../examples/init.rs}}
```
The `init` example uses the `lm3s6965` device. Remember to adjust the `device`
argument in the app macro attribute to match the path of your PAC crate, if
different, and add peripherals or other arguments if needed. Although aliases
can be used, this needs to be a full path (from the crate root). For many
devices, it is common for the HAL implementation crate (aliased as `hal`) or
Board Support crate to re-export the PAC as `pac`, leading to a pattern similar
to the below:
```rust
use abcd123_hal as hal;
//...
#[rtic::app(device = crate::hal::pac, peripherals = true, monotonic = rtic::cyccnt::CYCCNT)]
mod app { /*...*/ }
```
The `init` example also depends on the `panic-semihosting` crate:
``` console
$ cargo add panic-semihosting
```
5. Build it, flash it and run it.
``` console
$ # NOTE: I have uncommented the `runner` option in `.cargo/config`
$ cargo run
{{#include ../../../../ci/expected/init.run}}
```

167
book/en/src/by-example/resources.md
View file

@ -1,124 +1,155 @@
# Resources
# Resource usage
The framework provides an abstraction to share data between any of the contexts
we saw in the previous section (task handlers, `init` and `idle`): resources.
The RTIC framework manages shared and task local resources allowing persistent data storage and safe accesses without the use of `unsafe` code.
Resources are data visible only to functions declared within the `#[app]`
module. The framework gives the user complete control over which context
can access which resource.
RTIC resources are visible only to functions declared within the `#[app]` module and the framework gives the user complete control (on a per-task basis) over resource accessibility.
All resources are declared as a single `struct` within the `#[app]`
module. Each field in the structure corresponds to a different resource.
The `struct` must be annotated with the following attribute: `#[resources]`.
Declaration of system-wide resources is done by annotating **two** `struct`s within the `#[app]` module with the attribute `#[local]` and `#[shared]`. Each field in these structures corresponds to a different resource (identified by field name). The difference between these two sets of resources will be covered below.
Resources can optionally be given an initial value using the `#[init]`
attribute. Resources that are not given an initial value are referred to as
*late* resources and are covered in more detail in a follow-up section in this
page.
Each task must declare the resources it intends to access in its corresponding metadata attribute using the `local` and `shared` arguments. Each argument takes a list of resource identifiers. The listed resources are made available to the context under the `local` and `shared` fields of the `Context` structure.
Each context (task handler, `init` or `idle`) must declare the resources it
intends to access in its corresponding metadata attribute using the `resources`
argument. This argument takes a list of resource names as its value. The listed
resources are made available to the context under the `resources` field of the
`Context` structure.
The `init` task returns the initial values for the system-wide (`#[shared]` and `#[local]`) resources.
<!-- and the set of initialized timers used by the application. The monotonic timers will be
further discussed in [Monotonic & `spawn_{at/after}`](./monotonic.md). -->
The example application shown below contains two interrupt handlers that share access to a resource named `shared`.
## `#[local]` resources
`#[local]` resources are locally accessible to a specific task, meaning that only that task can access the resource and does so without locks or critical sections. This allows for the resources, commonly drivers or large objects, to be initialized in `#[init]` and then be passed to a specific task.
Thus, a task `#[local]` resource can only be accessed by one singular task. Attempting to assign the same `#[local]` resource to more than one task is a compile-time error.
Types of `#[local]` resources must implement a [`Send`] trait as they are being sent from `init` to a target task, crossing a thread boundary.
[`Send`]: https://doc.rust-lang.org/stable/core/marker/trait.Send.html
The example application shown below contains three tasks `foo`, `bar` and `idle`, each having access to its own `#[local]` resource.
``` rust
{{#include ../../../../examples/resource.rs}}
{{#include ../../../../rtic/examples/locals.rs}}
```
Running the example:
``` console
$ cargo run --target thumbv7m-none-eabi --example locals
```
``` console
$ cargo run --example resource
{{#include ../../../../ci/expected/resource.run}}
{{#include ../../../../rtic/ci/expected/locals.run}}
```
Note that the `shared` resource cannot be accessed from `idle`. Attempting to do so results in a compile error.
Local resources in `#[init]` and `#[idle]` have `'static` lifetimes. This is safe since both tasks are not re-entrant.
## `lock`
### Task local initialized resources
Critical sections are required to access shared mutable data in a data race-free manner.
Local resources can also be specified directly in the resource claim like so: `#[task(local = [my_var: TYPE = INITIAL_VALUE, ...])]`; this allows for creating locals which do no need to be initialized in `#[init]`.
The `resources` field of the passed `Context` implements the [`Mutex`] trait for each shared resource accessible to the task.
Types of `#[task(local = [..])]` resources have to be neither [`Send`] nor [`Sync`] as they are not crossing any thread boundary.
The only method on this trait, [`lock`], runs its closure argument in a critical section.
[`Sync`]: https://doc.rust-lang.org/stable/core/marker/trait.Sync.html
In the example below the different uses and lifetimes are shown:
``` rust
{{#include ../../../../rtic/examples/declared_locals.rs}}
```
You can run the application, but as the example is designed merely to showcase the lifetime properties there is no output (it suffices to build the application).
``` console
$ cargo build --target thumbv7m-none-eabi --example declared_locals
```
<!-- {{#include ../../../../rtic/ci/expected/declared_locals.run}} -->
## `#[shared]` resources and `lock`
Critical sections are required to access `#[shared]` resources in a data race-free manner and to achieve this the `shared` field of the passed `Context` implements the [`Mutex`] trait for each shared resource accessible to the task. This trait has only one method, [`lock`], which runs its closure argument in a critical section.
[`Mutex`]: ../../../api/rtic/trait.Mutex.html
[`lock`]: ../../../api/rtic/trait.Mutex.html#method.lock
The critical section created by the `lock` API is based on dynamic priorities: it temporarily raises the dynamic priority of the context to a *ceiling* priority that prevents other tasks from preempting the critical section. This synchronization protocol is known as the [Immediate Ceiling Priority Protocol
(ICPP)][icpp], and complies with [Stack Resource Policy(SRP)][srp] based scheduling of RTIC.
The critical section created by the `lock` API is based on dynamic priorities: it temporarily raises the dynamic priority of the context to a *ceiling* priority that prevents other tasks from preempting the critical section. This synchronization protocol is known as the [Immediate Ceiling Priority Protocol (ICPP)][icpp], and complies with [Stack Resource Policy (SRP)][srp] based scheduling of RTIC.
[icpp]: https://en.wikipedia.org/wiki/Priority_ceiling_protocol
[srp]: https://en.wikipedia.org/wiki/Stack_Resource_Policy
In the example below we have three interrupt handlers with priorities ranging from one to three. The two handlers with the lower priorities contend for the `shared` resource and need to lock the resource for accessing the data. The highest priority handler, which do nat access the `shared` resource, is free to preempt the critical section created by the
lowest priority handler.
In the example below we have three interrupt handlers with priorities ranging from one to three. The two handlers with the lower priorities contend for a `shared` resource and need to succeed in locking the resource in order to access its data. The highest priority handler, which does not access the `shared` resource, is free to preempt a critical section created by the lowest priority handler.
``` rust
{{#include ../../../../examples/lock.rs}}
{{#include ../../../../rtic/examples/lock.rs}}
```
``` console
$ cargo run --example lock
{{#include ../../../../ci/expected/lock.run}}
$ cargo run --target thumbv7m-none-eabi --example lock
```
``` console
{{#include ../../../../rtic/ci/expected/lock.run}}
```
Types of `#[shared]` resources have to be [`Send`].
## Multi-lock
As an extension to `lock`, and to reduce rightward drift, locks can be taken as tuples. The following examples shows this in use:
As an extension to `lock`, and to reduce rightward drift, locks can be taken as tuples. The following examples show this in use:
``` rust
{{#include ../../../../examples/multilock.rs}}
```
## Late resources
Late resources are resources that are not given an initial value at compile time using the `#[init]` attribute but instead are initialized at runtime using the `init::LateResources` values returned by the `init` function.
Late resources are useful e.g., to *move* (as in transferring the ownership of) peripherals initialized in `init` into tasks.
The example below uses late resources to establish a lockless, one-way channel between the `UART0` interrupt handler and the `idle` task. A single producer single consumer [`Queue`] is used as the channel. The queue is split into consumer and producer end points in `init` and then each end point is stored in a different resource; `UART0` owns the producer resource and `idle` owns the consumer resource.
[`Queue`]: ../../../api/heapless/spsc/struct.Queue.html
``` rust
{{#include ../../../../examples/late.rs}}
{{#include ../../../../rtic/examples/multilock.rs}}
```
``` console
$ cargo run --example late
{{#include ../../../../ci/expected/late.run}}
$ cargo run --target thumbv7m-none-eabi --example multilock
```
## Only shared access
``` console
{{#include ../../../../rtic/ci/expected/multilock.run}}
```
By default the framework assumes that all tasks require exclusive access (`&mut-`) to resources but it is possible to specify that a task only requires shared access (`&-`) to a resource using the `&resource_name` syntax in the `resources` list.
## Only shared (`&-`) access
The advantage of specifying shared access (`&-`) to a resource is that no locks are required to access the resource even if the resource is contended by several tasks running at different priorities. The downside is that the task only gets a shared reference (`&-`) to the resource, limiting the operations it can perform on it, but where a shared reference is enough this approach reduces the number of required locks. In addition to simple immutable data, this shared access can be useful where the resource type safely implements interior mutability, with
appropriate locking or atomic operations of its own.
By default, the framework assumes that all tasks require exclusive mutable access (`&mut-`) to resources, but it is possible to specify that a task only requires shared access (`&-`) to a resource using the `&resource_name` syntax in the `shared` list.
The advantage of specifying shared access (`&-`) to a resource is that no locks are required to access the resource even if the resource is contended by more than one task running at different priorities. The downside is that the task only gets a shared reference (`&-`) to the resource, limiting the operations it can perform on it, but where a shared reference is enough this approach reduces the number of required locks. In addition to simple immutable data, this shared access can be useful where the resource type safely implements interior mutability, with appropriate locking or atomic operations of its own.
Note that in this release of RTIC it is not possible to request both exclusive access (`&mut-`) and shared access (`&-`) to the *same* resource from different tasks. Attempting to do so will result in a compile error.
In the example below a key (e.g. a cryptographic key) is loaded (or created) at runtime and then used from two tasks that run at different priorities without any kind of lock.
In the example below a key (e.g. a cryptographic key) is loaded (or created) at runtime (returned by `init`) and then used from two tasks that run at different priorities without any kind of lock.
``` rust
{{#include ../../../../examples/only-shared-access.rs}}
{{#include ../../../../rtic/examples/only-shared-access.rs}}
```
``` console
$ cargo run --example only-shared-access
{{#include ../../../../ci/expected/only-shared-access.run}}
$ cargo run --target thumbv7m-none-eabi --example only-shared-access
```
## Lock-free resource access of mutable resources
``` console
{{#include ../../../../rtic/ci/expected/only-shared-access.run}}
```
There exists two other options dealing with resources
## Lock-free access of shared resources
* `#[lock_free]`: there might be several tasks with the same priority
accessing the resource without critical section. Since tasks with the
same priority never can preempt another task on the same priority
this is safe.
* `#[task_local]`: there must be only one task using this resource,
similar to a `static mut` task local resource, but (optionally) set-up by init.
A critical section is *not* required to access a `#[shared]` resource that's only accessed by tasks running at the *same* priority. In this case, you can opt out of the `lock` API by adding the `#[lock_free]` field-level attribute to the resource declaration (see example below).
<!-- Note that this is merely a convenience to reduce needless resource locking code, because even if the
`lock` API is used, at runtime the framework will **not** produce a critical section due to how
the underlying resource-ceiling preemption works. -->
To adhere to the Rust [aliasing] rule, a resource may be either accessed through multiple immutable references or a singe mutable reference (but not both at the same time).
[aliasing]: https://doc.rust-lang.org/nomicon/aliasing.html
Using `#[lock_free]` on resources shared by tasks running at different priorities will result in a *compile-time* error -- not using the `lock` API would violate the aforementioned alias rule. Similarly, for each priority there can be only a single *software* task accessing a shared resource (as an `async` task may yield execution to other *software* or *hardware* tasks running at the same priority). However, under this single-task restriction, we make the observation that the resource is in effect no longer `shared` but rather `local`. Thus, using a `#[lock_free]` shared resource will result in a *compile-time* error -- where applicable, use a `#[local]` resource instead.
``` rust
{{#include ../../../../rtic/examples/lock-free.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example lock-free
```
``` console
{{#include ../../../../rtic/ci/expected/lock-free.run}}
```

111
book/en/src/by-example/software_tasks.md Normal file
View file

@ -0,0 +1,111 @@
# Software tasks & spawn
The RTIC concept of a software task shares a lot with that of [hardware tasks](./hardware_tasks.md) with the core difference that a software task is not explicitly bound to a specific
interrupt vector, but rather bound to a “dispatcher” interrupt vector running at the intended priority of the software task (see below).
Similarly to *hardware* tasks, the `#[task]` attribute used on a function declare it as a task. The absence of a `binds = InterruptName` argument to the attribute declares the function as a *software task*.
The static method `task_name::spawn()` spawns (starts) a software task and given that there are no higher priority tasks running the task will start executing directly.
The *software* task itself is given as an `async` Rust function, which allows the user to optionally `await` future events. This allows to blend reactive programming (by means of *hardware* tasks) with sequential programming (by means of *software* tasks).
Whereas, *hardware* tasks are assumed to run-to-completion (and return), *software* tasks may be started (`spawned`) once and run forever, with the side condition that any loop (execution path) is broken by at least one `await` (yielding operation).
All *software* tasks at the same priority level shares an interrupt handler acting as an async executor dispatching the software tasks.
This list of dispatchers, `dispatchers = [FreeInterrupt1, FreeInterrupt2, ...]` is an argument to the `#[app]` attribute, where you define the set of free and usable interrupts.
Each interrupt vector acting as dispatcher gets assigned to one priority level meaning that the list of dispatchers need to cover all priority levels used by software tasks.
Example: The `dispatchers =` argument needs to have at least 3 entries for an application using three different priorities for software tasks.
The framework will give a compilation error if there are not enough dispatchers provided, or if a clash occurs between the list of dispatchers and interrupts bound to *hardware* tasks.
See the following example:
``` rust
{{#include ../../../../rtic/examples/spawn.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example spawn
```
``` console
{{#include ../../../../rtic/ci/expected/spawn.run}}
```
You may `spawn` a *software* task again, given that it has run-to-completion (returned).
In the below example, we `spawn` the *software* task `foo` from the `idle` task. Since the default priority of the *software* task is 1 (higher than `idle`), the dispatcher will execute `foo` (preempting `idle`). Since `foo` runs-to-completion. It is ok to `spawn` the `foo` task again.
Technically the async executor will `poll` the `foo` *future* which in this case leaves the *future* in a *completed* state.
``` rust
{{#include ../../../../rtic/examples/spawn_loop.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example spawn_loop
```
``` console
{{#include ../../../../rtic/ci/expected/spawn_loop.run}}
```
An attempt to `spawn` an already spawned task (running) task will result in an error. Notice, the that the error is reported before the `foo` task is actually run. This is since, the actual execution of the *software* task is handled by the dispatcher interrupt (`SSIO`), which is not enabled until we exit the `init` task. (Remember, `init` runs in a critical section, i.e. all interrupts being disabled.)
Technically, a `spawn` to a *future* that is not in *completed* state is considered an error.
``` rust
{{#include ../../../../rtic/examples/spawn_err.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example spawn_err
```
``` console
{{#include ../../../../rtic/ci/expected/spawn_err.run}}
```
## Passing arguments
You can also pass arguments at spawn as follows.
``` rust
{{#include ../../../../rtic/examples/spawn_arguments.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example spawn_arguments
```
``` console
{{#include ../../../../rtic/ci/expected/spawn_arguments.run}}
```
## Priority zero tasks
In RTIC tasks run preemptively to each other, with priority zero (0) the lowest priority. You can use priority zero tasks for background work, without any strict real-time requirements.
Conceptually, one can see such tasks as running in the `main` thread of the application, thus the resources associated are not required the [Send] bound.
[Send]: https://doc.rust-lang.org/nomicon/send-and-sync.html
``` rust
{{#include ../../../../rtic/examples/zero-prio-task.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example zero-prio-task
```
``` console
{{#include ../../../../rtic/ci/expected/zero-prio-task.run}}
```
> **Notice**: *software* task at zero priority cannot co-exist with the [idle] task. The reason is that `idle` is running as a non-returning Rust function at priority zero. Thus there would be no way for an executor at priority zero to give control to *software* tasks at the same priority.
---
Application side safety: Technically, the RTIC framework ensures that `poll` is never executed on any *software* task with *completed* future, thus adhering to the soundness rules of async Rust.

21
book/en/src/by-example/starting_a_project.md Normal file
View file

@ -0,0 +1,21 @@
# Starting a new project
A recommendation when starting a RTIC project from scratch is to
follow RTIC's [`defmt-app-template`].
If you are targeting ARMv6-M or ARMv8-M-base architecture, check out the section [Target Architecture](../internals/targets.md) for more information on hardware limitations to be aware of.
[`defmt-app-template`]: https://github.com/rtic-rs/defmt-app-template
This will give you an RTIC application with support for RTT logging with [`defmt`] and stack overflow
protection using [`flip-link`]. There is also a multitude of examples provided by the community:
For inspiration, you may look at the below resources. For now, they cover RTIC v1.x, but will be updated with RTIC v2.x examples over time.
- [`rtic-examples`] - Multiple projects
- [https://github.com/kalkyl/f411-rtic](https://github.com/kalkyl/f411-rtic)
- ... More to come
[`defmt`]: https://github.com/knurling-rs/defmt/
[`flip-link`]: https://github.com/knurling-rs/flip-link/
[`rtic-examples`]: https://github.com/rtic-rs/rtic-examples

118
book/en/src/by-example/tasks.md
View file

@ -1,118 +0,0 @@
# Software tasks
In addition to hardware tasks, which are invoked by the hardware in response to
hardware events, RTIC also supports *software* tasks which can be spawned by the
application from any execution context.
Software tasks can also be assigned priorities and, under the hood, are
dispatched from interrupt handlers. RTIC requires that free interrupts are
declared in the `dispatchers` app argument when using software tasks; some of these free
interrupts will be used to dispatch the software tasks. An advantage of software
tasks over hardware tasks is that many tasks can be mapped to a single interrupt
handler.
Software tasks are also declared using the `task` attribute but the `binds`
argument must be omitted.
The example below showcases three software tasks that run at 2 different
priorities. The three software tasks are mapped to 2 interrupts handlers.
``` rust
{{#include ../../../../examples/task.rs}}
```
``` console
$ cargo run --example task
{{#include ../../../../ci/expected/task.run}}
```
## Message passing
The other advantage of software tasks is that messages can be passed to these
tasks when spawning them. The type of the message payload must be specified in
the signature of the task handler.
The example below showcases three tasks, two of them expect a message.
``` rust
{{#include ../../../../examples/message.rs}}
```
``` console
$ cargo run --example message
{{#include ../../../../ci/expected/message.run}}
```
## Capacity
RTIC does *not* perform any form of heap-based memory allocation. The memory
required to store messages is statically reserved. By default the framework
minimizes the memory footprint of the application so each task has a message
"capacity" of 1: meaning that at most one message can be posted to the task
before it gets a chance to run. This default can be overridden for each task
using the `capacity` argument. This argument takes a positive integer that
indicates how many messages the task message buffer can hold.
The example below sets the capacity of the software task `foo` to 4. If the
capacity is not specified then the second `spawn.foo` call in `UART0` would
fail (panic).
``` rust
{{#include ../../../../examples/capacity.rs}}
```
``` console
$ cargo run --example capacity
{{#include ../../../../ci/expected/capacity.run}}
```
## Error handling
The `spawn` API returns the `Err` variant when there's no space to send the
message. In most scenarios spawning errors are handled in one of two ways:
- Panicking, using `unwrap`, `expect`, etc. This approach is used to catch the
programmer error (i.e. bug) of selecting a capacity that was too small. When
this panic is encountered during testing choosing a bigger capacity and
recompiling the program may fix the issue but sometimes it's necessary to dig
deeper and perform a timing analysis of the application to check if the
platform can deal with peak payload or if the processor needs to be replaced
with a faster one.
- Ignoring the result. In soft real-time and non real-time applications it may
be OK to occasionally lose data or fail to respond to some events during event
bursts. In those scenarios silently letting a `spawn` call fail may be
acceptable.
It should be noted that retrying a `spawn` call is usually the wrong approach as
this operation will likely never succeed in practice. Because there are only
context switches towards *higher* priority tasks retrying the `spawn` call of a
lower priority task will never let the scheduler dispatch said task meaning that
its message buffer will never be emptied. This situation is depicted in the
following snippet:
``` rust
#[rtic::app(..)]
mod app {
#[init(spawn = [foo, bar])]
fn init(cx: init::Context) {
cx.spawn.foo().unwrap();
cx.spawn.bar().unwrap();
}
#[task(priority = 2, spawn = [bar])]
fn foo(cx: foo::Context) {
// ..
// the program will get stuck here
while cx.spawn.bar(payload).is_err() {
// retry the spawn call if it failed
}
}
#[task(priority = 1)]
fn bar(cx: bar::Context, payload: i32) {
// ..
}
}
```

113
book/en/src/by-example/timer-queue.md
View file

@ -1,113 +0,0 @@
# Timer queue
In contrast with the `spawn` API, which immediately spawns a software task onto
the scheduler, the `schedule` API can be used to schedule a task to run some
time in the future.
To use the `schedule` API a monotonic timer must be first defined using the
`monotonic` argument of the `#[app]` attribute. This argument takes a path to a
type that implements the [`Monotonic`] trait. The associated type, `Instant`, of
this trait represents a timestamp in arbitrary units and it's used extensively
in the `schedule` API -- it is suggested to model this type after [the one in
the standard library][std-instant].
Although not shown in the trait definition (due to limitations in the trait /
type system) the subtraction of two `Instant`s should return some `Duration`
type (see [`core::time::Duration`]) and this `Duration` type must implement the
`TryInto<u32>` trait. The implementation of this trait must convert the
`Duration` value, which uses some arbitrary unit of time, into the "system timer
(SYST) clock cycles" time unit. The result of the conversion must be a 32-bit
integer. If the result of the conversion doesn't fit in a 32-bit number then the
operation must return an error, any error type.
[`Monotonic`]: ../../../api/rtic/trait.Monotonic.html
[std-instant]: https://doc.rust-lang.org/std/time/struct.Instant.html
[`core::time::Duration`]: https://doc.rust-lang.org/core/time/struct.Duration.html
For ARMv7+ targets the `rtic` crate provides a `Monotonic` implementation based
on the built-in CYCle CouNTer (CYCCNT). Note that this is a 32-bit timer clocked
at the frequency of the CPU and as such it is not suitable for tracking time
spans in the order of seconds.
When scheduling a task the (user-defined) `Instant` at which the task should be
executed must be passed as the first argument of the `schedule` invocation.
Additionally, the chosen `monotonic` timer must be configured and initialized
during the `#[init]` phase. Note that this is *also* the case if you choose to
use the `CYCCNT` provided by the `cortex-m-rtic` crate.
The example below schedules two tasks from `init`: `foo` and `bar`. `foo` is
scheduled to run 8 million clock cycles in the future. Next, `bar` is scheduled
to run 4 million clock cycles in the future. Thus `bar` runs before `foo` since
it was scheduled to run first.
> **IMPORTANT**: The examples that use the `schedule` API or the `Instant`
> abstraction will **not** properly work on QEMU because the Cortex-M cycle
> counter functionality has not been implemented in `qemu-system-arm`.
``` rust
{{#include ../../../../examples/schedule.rs}}
```
Running the program on real hardware produces the following output in the
console:
``` text
{{#include ../../../../ci/expected/schedule.run}}
```
When the `schedule` API is being used the runtime internally uses the `SysTick`
interrupt handler and the system timer peripheral (`SYST`) so neither can be
used by the application. This is accomplished by changing the type of
`init::Context.core` from `cortex_m::Peripherals` to `rtic::Peripherals`. The
latter structure contains all the fields of the former minus the `SYST` one.
## Periodic tasks
Software tasks have access to the `Instant` at which they were scheduled to run
through the `scheduled` variable. This information and the `schedule` API can be
used to implement periodic tasks as shown in the example below.
``` rust
{{#include ../../../../examples/periodic.rs}}
```
This is the output produced by the example. Note that there is zero drift /
jitter even though `schedule.foo` was invoked at the *end* of `foo`. Using
`Instant::now` instead of `scheduled` would have resulted in drift / jitter.
``` text
{{#include ../../../../ci/expected/periodic.run}}
```
## Baseline
For the tasks scheduled from `init` we have exact information about their
`scheduled` time. For hardware tasks there's no `scheduled` time because these
tasks are asynchronous in nature. For hardware tasks the runtime provides a
`start` time, which indicates the time at which the task handler started
executing.
Note that `start` is **not** equal to the arrival time of the event that fired
the task. Depending on the priority of the task and the load of the system the
`start` time could be very far off from the event arrival time.
What do you think will be the value of `scheduled` for software tasks that are
*spawned* instead of scheduled? The answer is that spawned tasks inherit the
*baseline* time of the context that spawned it. The baseline of hardware tasks
is their `start` time, the baseline of software tasks is their `scheduled` time
and the baseline of `init` is the system start time or time zero
(`Instant::zero()`). `idle` doesn't really have a baseline but tasks spawned
from it will use `Instant::now()` as their baseline time.
The example below showcases the different meanings of the *baseline*.
``` rust
{{#include ../../../../examples/baseline.rs}}
```
Running the program on real hardware produces the following output in the console:
``` text
{{#include ../../../../ci/expected/baseline.run}}
```

171
book/en/src/by-example/tips.md
View file

@ -1,172 +1,3 @@
# Tips & tricks
## Generics
All resource proxies implement the `rtic::Mutex` trait.
If a resource does not implement this, one can wrap it in the [`rtic::Exclusive`]
newtype which does implement the `Mutex` trait. With the help of this newtype
one can write a generic function that operates on generic resources and call it
from different tasks to perform some operation on the same set of resources.
Here's one such example:
[`rtic::Exclusive`]: ../../../api/rtic/struct.Exclusive.html
``` rust
{{#include ../../../../examples/generics.rs}}
```
``` console
$ cargo run --example generics
{{#include ../../../../ci/expected/generics.run}}
```
## Conditional compilation
You can use conditional compilation (`#[cfg]`) on resources (the fields of
`#[resources] struct Resources`) and tasks (the `fn` items).
The effect of using `#[cfg]` attributes is that the resource / task
will *not* be available through the corresponding `Context` `struct`
if the condition doesn't hold.
The example below logs a message whenever the `foo` task is spawned, but only if
the program has been compiled using the `dev` profile.
``` rust
{{#include ../../../../examples/cfg.rs}}
```
``` console
$ cargo run --example cfg --release
$ cargo run --example cfg
{{#include ../../../../ci/expected/cfg.run}}
```
## Running tasks from RAM
The main goal of moving the specification of RTIC applications to attributes in
RTIC v0.4.0 was to allow inter-operation with other attributes. For example, the
`link_section` attribute can be applied to tasks to place them in RAM; this can
improve performance in some cases.
> **IMPORTANT**: In general, the `link_section`, `export_name` and `no_mangle`
> attributes are very powerful but also easy to misuse. Incorrectly using any of
> these attributes can cause undefined behavior; you should always prefer to use
> safe, higher level attributes around them like `cortex-m-rt`'s `interrupt` and
> `exception` attributes.
>
> In the particular case of RAM functions there's no
> safe abstraction for it in `cortex-m-rt` v0.6.5 but there's an [RFC] for
> adding a `ramfunc` attribute in a future release.
[RFC]: https://github.com/rust-embedded/cortex-m-rt/pull/100
The example below shows how to place the higher priority task, `bar`, in RAM.
``` rust
{{#include ../../../../examples/ramfunc.rs}}
```
Running this program produces the expected output.
``` console
$ cargo run --example ramfunc
{{#include ../../../../ci/expected/ramfunc.run}}
```
One can look at the output of `cargo-nm` to confirm that `bar` ended in RAM
(`0x2000_0000`), whereas `foo` ended in Flash (`0x0000_0000`).
``` console
$ cargo nm --example ramfunc --release | grep ' foo::'
{{#include ../../../../ci/expected/ramfunc.grep.foo}}
```
``` console
$ cargo nm --example ramfunc --release | grep ' bar::'
{{#include ../../../../ci/expected/ramfunc.grep.bar}}
```
## Indirection for faster message passing
Message passing always involves copying the payload from the sender into a
static variable and then from the static variable into the receiver. Thus
sending a large buffer, like a `[u8; 128]`, as a message involves two expensive
`memcpy`s. To minimize the message passing overhead one can use indirection:
instead of sending the buffer by value, one can send an owning pointer into the
buffer.
One can use a global allocator to achieve indirection (`alloc::Box`,
`alloc::Rc`, etc.), which requires using the nightly channel as of Rust v1.37.0,
or one can use a statically allocated memory pool like [`heapless::Pool`].
[`heapless::Pool`]: https://docs.rs/heapless/0.5.0/heapless/pool/index.html
Here's an example where `heapless::Pool` is used to "box" buffers of 128 bytes.
``` rust
{{#include ../../../../examples/pool.rs}}
```
``` console
$ cargo run --example pool
{{#include ../../../../ci/expected/pool.run}}
```
## Inspecting the expanded code
`#[rtic::app]` is a procedural macro that produces support code. If for some
reason you need to inspect the code generated by this macro you have two
options:
You can inspect the file `rtic-expansion.rs` inside the `target` directory. This
file contains the expansion of the `#[rtic::app]` item (not your whole program!)
of the *last built* (via `cargo build` or `cargo check`) RTIC application. The
expanded code is not pretty printed by default so you'll want to run `rustfmt`
on it before you read it.
``` console
$ cargo build --example foo
$ rustfmt target/rtic-expansion.rs
$ tail target/rtic-expansion.rs
```
``` rust
#[doc = r" Implementation details"]
mod app {
#[doc = r" Always include the device crate which contains the vector table"]
use lm3s6965 as _;
#[no_mangle]
unsafe extern "C" fn main() -> ! {
rtic::export::interrupt::disable();
let mut core: rtic::export::Peripherals = core::mem::transmute(());
core.SCB.scr.modify(|r| r | 1 << 1);
rtic::export::interrupt::enable();
loop {
rtic::export::wfi()
}
}
}
```
Or, you can use the [`cargo-expand`] sub-command. This sub-command will expand
*all* the macros, including the `#[rtic::app]` attribute, and modules in your
crate and print the output to the console.
[`cargo-expand`]: https://crates.io/crates/cargo-expand
``` console
$ # produces the same output as before
$ cargo expand --example smallest | tail
```
## Resource de-structure-ing
When having a task taking multiple resources it can help in readability to split
up the resource struct. Here are two examples on how this can be done:
``` rust
{{#include ../../../../examples/destructure.rs}}
```
In this section we will explore common tips & tricks related to using RTIC.

15
book/en/src/by-example/tips_destructureing.md Normal file
View file

@ -0,0 +1,15 @@
# Resource de-structure-ing
Destructuring task resources might help readability if a task takes multiple
resources. Here are two examples on how to split up the resource struct:
``` rust
{{#include ../../../../rtic/examples/destructure.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example destructure
```
``` console
{{#include ../../../../rtic/ci/expected/destructure.run}}
```

45
book/en/src/by-example/tips_from_ram.md Normal file
View file

@ -0,0 +1,45 @@
# Running tasks from RAM
The main goal of moving the specification of RTIC applications to attributes in RTIC v0.4.0 was to allow inter-operation with other attributes. For example, the `link_section` attribute can be applied to tasks to place them in RAM; this can
improve performance in some cases.
> **IMPORTANT**: In general, the `link_section`, `export_name` and `no_mangle` attributes are powerful but also easy to misuse. Incorrectly using any of these attributes can cause undefined behavior; you should always prefer to use safe, higher level attributes around them like `cortex-m-rt`'s `interrupt` and `exception` attributes.
>
> In the particular case of RAM functions there's no safe abstraction for it in `cortex-m-rt` v0.6.5 but there's an [RFC] for adding a `ramfunc` attribute in a future release.
[RFC]: https://github.com/rust-embedded/cortex-m-rt/pull/100
The example below shows how to place the higher priority task, `bar`, in RAM.
``` rust
{{#include ../../../../rtic/examples/ramfunc.rs}}
```
Running this program produces the expected output.
``` console
$ cargo run --target thumbv7m-none-eabi --example ramfunc
```
``` console
{{#include ../../../../rtic/ci/expected/ramfunc.run}}
```
One can look at the output of `cargo-nm` to confirm that `bar` ended in RAM
(`0x2000_0000`), whereas `foo` ended in Flash (`0x0000_0000`).
``` console
$ cargo nm --example ramfunc --release | grep ' foo::'
```
``` console
{{#include ../../../../rtic/ci/expected/ramfunc.run.grep.foo}}
```
``` console
$ cargo nm --example ramfunc --target thumbv7m-none-eabi --release | grep '*bar::'
```
``` console
{{#include ../../../../rtic/ci/expected/ramfunc.run.grep.bar}}
```

26
book/en/src/by-example/tips_indirection.md Normal file
View file

@ -0,0 +1,26 @@
# Using indirection for faster message passing
Message passing always involves copying the payload from the sender into a static variable and then from the static variable into the receiver. Thus sending a large buffer, like a `[u8; 128]`, as a message involves two expensive
`memcpy`s.
Indirection can minimize message passing overhead: instead of sending the buffer by value, one can send an owning pointer into the buffer.
One can use a global memory allocator to achieve indirection (`alloc::Box`, `alloc::Rc`, etc.), which requires using the nightly channel as of Rust v1.37.0, or one can use a statically allocated memory pool like [`heapless::Pool`].
[`heapless::Pool`]: https://docs.rs/heapless/0.5.0/heapless/pool/index.html
As this example of approach goes completely outside of RTIC resource model with shared and local the program would rely on the correctness of the memory allocator, in this case `heapless::pool`.
Here's an example where `heapless::Pool` is used to "box" buffers of 128 bytes.
``` rust
{{#include ../../../../rtic/examples/pool.rs}}
```
``` console
$ cargo run --target thumbv7m-none-eabi --example pool
```
``` console
{{#include ../../../../rtic/ci/expected/pool.run}}
```

29
book/en/src/by-example/tips_monotonic_impl.md Normal file
View file

@ -0,0 +1,29 @@
# Implementing a `Monotonic` timer for scheduling
The framework is flexible because it can use any timer which has compare-match and optionally supporting overflow interrupts for scheduling. The single requirement to make a timer usable with RTIC is implementing the [`rtic-time::Monotonic`] trait.
For RTIC 1.0 and 2.0 we instead assume the user has a time library, e.g. [`fugit`] or [`embedded_time`], as the basis for all time-based operations when implementing `Monotonic`. These libraries make it much easier to correctly implement the `Monotonic` trait, allowing the use of
almost any timer in the system for scheduling.
The trait documents the requirements for each method, and for inspiration
there is a reference implementation based on the `SysTick` timer available on all ARM Cortex M MCUs.
- [`Systick based`], runs at a fixed interrupt (tick) rate - with some overhead but simple and provides support for large time spans
Here is a list of `Monotonic` implementations for RTIC 1.0:
- [`STM32F411 series`], implemented for the 32-bit timers
- [`Nordic nRF52 series Timer`], implemented for the 32-bit timers
- [`Nordic nRF52 series RTC`], implemented for the RTCs
- [`DWT and Systick based`], a more efficient (tickless) implementation - requires both `SysTick` and `DWT`, supports both high resolution and large time spans
If you know of more implementations feel free to add them to this list.
[`rtic_time::Monotonic`]: https://docs.rs/rtic_time/
[`fugit`]: https://docs.rs/fugit/
[`embedded_time`]: https://docs.rs/embedded_time/
[`STM32F411 series`]: https://github.com/kalkyl/f411-rtic/blob/a696fce7d6d19fda2356c37642c4d53547982cca/src/mono.rs
[`Nordic nRF52 series Timer`]: https://github.com/kalkyl/nrf-play/blob/47f4410d4e39374c18ff58dc17c25159085fb526/src/mono.rs
[`Nordic nRF52 series RTC`]: https://gist.github.com/korken89/fe94a475726414dd1bce031c76adc3dd
[`Systick based`]: https://github.com/rtic-monotonics
[`DWT and Systick based`]: https://github.com/rtic-rs/dwt-systick-monotonic

23
book/en/src/by-example/tips_static_lifetimes.md Normal file
View file

@ -0,0 +1,23 @@
# 'static super-powers
In `#[init]` and `#[idle]` `local` resources have `'static` lifetime.
Useful when pre-allocating and/or splitting resources between tasks, drivers or some other object. This comes in handy when drivers, such as USB drivers, need to allocate memory and when using splittable data structures such as [`heapless::spsc::Queue`].
In the following example two different tasks share a [`heapless::spsc::Queue`] for lock-free access to the shared queue.
[`heapless::spsc::Queue`]: https://docs.rs/heapless/0.7.5/heapless/spsc/struct.Queue.html
``` rust
{{#include ../../../../rtic/examples/static.rs}}
```
Running this program produces the expected output.
``` console
$ cargo run --target thumbv7m-none-eabi --example static
```
``` console
{{#include ../../../../rtic/ci/expected/static.run}}
```

47
book/en/src/by-example/tips_view_code.md Normal file
View file

@ -0,0 +1,47 @@
# Inspecting generated code
`#[rtic::app]` is a procedural macro that produces support code. If for some reason you need to inspect the code generated by this macro you have two options:
You can inspect the file `rtic-expansion.rs` inside the `target` directory. This file contains the expansion of the `#[rtic::app]` item (not your whole program!) of the *last built* (via `cargo build` or `cargo check`) RTIC application. The expanded code is not pretty printed by default, so you'll want to run `rustfmt` on it before you read it.
``` console
$ cargo build --example smallest --target thumbv7m-none-eabi
```
``` console
$ rustfmt target/rtic-expansion.rs
```
``` console
$ tail target/rtic-expansion.rs
```
``` rust
#[doc = r" Implementation details"]
mod app {
#[doc = r" Always include the device crate which contains the vector table"]
use lm3s6965 as _;
#[no_mangle]
unsafe extern "C" fn main() -> ! {
rtic::export::interrupt::disable();
let mut core: rtic::export::Peripherals = core::mem::transmute(());
core.SCB.scr.modify(|r| r | 1 << 1);
rtic::export::interrupt::enable();
loop {
rtic::export::wfi()
}
}
}
```
Or, you can use the [`cargo-expand`] sub-command. This sub-command will expand *all* the macros, including the `#[rtic::app]` attribute, and modules in your crate and print the output to the console.
[`cargo-expand`]: https://crates.io/crates/cargo-expand
``` console
# produces the same output as before
```
``` console
cargo expand --example smallest | tail
```

51
book/en/src/by-example/types-send-sync.md
View file

@ -1,51 +0,0 @@
# Types, Send and Sync
Every function within the `app` module has a `Context` structure as its
first parameter. All the fields of these structures have predictable,
non-anonymous types so you can write plain functions that take them as arguments.
The API reference specifies how these types are generated from the input. You
can also generate documentation for your binary crate (`cargo doc --bin <name>`);
in the documentation you'll find `Context` structs (e.g. `init::Context` and
`idle::Context`).
The example below shows the different types generates by the `app` attribute.
``` rust
{{#include ../../../../examples/types.rs}}
```
## `Send`
[`Send`] is a marker trait for "types that can be transferred across thread
boundaries", according to its definition in `core`. In the context of RTIC the
`Send` trait is only required where it's possible to transfer a value between
tasks that run at *different* priorities. This occurs in a few places: in
message passing, in shared resources and in the initialization of late
resources.
[`Send`]: https://doc.rust-lang.org/core/marker/trait.Send.html
The `app` attribute will enforce that `Send` is implemented where required so
you don't need to worry much about it. Currently all types that are passed need
to be `Send` in RTIC, however this restriction might be relaxed in the future.
## `Sync`
Similarly, [`Sync`] is a marker trait for "types for which it is safe to share
references between threads", according to its definition in `core`. In the
context of RTIC the `Sync` trait is only required where it's possible for two,
or more, tasks that run at different priorities and may get a shared reference
(`&-`) to a resource. This only occurs with shared access (`&-`) resources.
[`Sync`]: https://doc.rust-lang.org/core/marker/trait.Sync.html
The `app` attribute will enforce that `Sync` is implemented where required but
it's important to know where the `Sync` bound is not required: shared access
(`&-`) resources contended by tasks that run at the *same* priority.
The example below shows where a type that doesn't implement `Sync` can be used.
``` rust
{{#include ../../../../examples/not-sync.rs}}
```

68
book/en/src/internals/targets.md Normal file
View file

@ -0,0 +1,68 @@
# Target Architecture
While RTIC can currently target all Cortex-m devices there are some key architecture differences that
users should be aware of. Namely, the absence of Base Priority Mask Register (`BASEPRI`) which lends
itself exceptionally well to the hardware priority ceiling support used in RTIC, in the ARMv6-M and
ARMv8-M-base architectures, which forces RTIC to use source masking instead. For each implementation
of lock and a detailed commentary of pros and cons, see the implementation of
[lock in src/export.rs][src_export].
[src_export]: https://github.com/rtic-rs/rtic/blob/master/src/export.rs
These differences influence how critical sections are realized, but functionality should be the same
except that ARMv6-M/ARMv8-M-base cannot have tasks with shared resources bound to exception
handlers, as these cannot be masked in hardware.
Table 1 below shows a list of Cortex-m processors and which type of critical section they employ.
#### *Table 1: Critical Section Implementation by Processor Architecture*
| Processor | Architecture | Priority Ceiling | Source Masking |
| :--------- | :----------: | :--------------: | :------------: |
| Cortex-M0 | ARMv6-M | | ✓ |
| Cortex-M0+ | ARMv6-M | | ✓ |
| Cortex-M3 | ARMv7-M | ✓ | |
| Cortex-M4 | ARMv7-M | ✓ | |
| Cortex-M7 | ARMv7-M | ✓ | |
| Cortex-M23 | ARMv8-M-base | | ✓ |
| Cortex-M33 | ARMv8-M-main | ✓ | |
## Priority Ceiling
This is covered by the [Resources][resources] page of this book.
## Source Masking
Without a `BASEPRI` register which allows for directly setting a priority ceiling in the Nested
Vectored Interrupt Controller (NVIC), RTIC must instead rely on disabling (masking) interrupts.
Consider Figure 1 below, showing two tasks A and B where A has higher priority but shares a resource
with B.
#### *Figure 1: Shared Resources and Source Masking*
```text
┌────────────────────────────────────────────────────────────────┐
│ │
│ │
3 │ Pending Preempts │
2 │ ↑- - -A- - - - -↓A─────────► │
1 │ B───────────────────► - - - - B────────► │
0 │Idle┌─────► Resumes ┌────────► │
├────┴────────────────────────────────────────────┴──────────────┤
│ │
└────────────────────────────────────────────────────────────────┴──► Time
t1 t2 t3 t4
```
At time *t1*, task B locks the shared resource by selectively disabling (using the NVIC) all other
tasks which have a priority equal to or less than any task which shares resources with B. In effect
this creates a virtual priority ceiling, mirroring the `BASEPRI` approach. Task A is one such task that shares resources with
task B. At time *t2*, task A is either spawned by task B or becomes pending through an interrupt
condition, but does not yet preempt task B even though its priority is greater. This is because the
NVIC is preventing it from starting due to task A being disabled. At time *t3*, task B
releases the lock by re-enabling the tasks in the NVIC. Because task A was pending and has a higher
priority than task B, it immediately preempts task B and is free to use the shared resource without
risk of data race conditions. At time *t4*, task A completes and returns the execution context to B.
Since source masking relies on use of the NVIC, core exception sources such as HardFault, SVCall,
PendSV, and SysTick cannot share data with other tasks.

10
book/en/src/internals/tasks.md
View file

@ -78,8 +78,8 @@ mod app {
}
// ready queue of the task dispatcher
// `U4` is a type-level integer that represents the capacity of this queue
static mut RQ1: Queue<Ready<T1>, U4> = Queue::new();
// `5-1=4` represents the capacity of this queue
static mut RQ1: Queue<Ready<T1>, 5> = Queue::new();
// interrupt handler chosen to dispatch tasks at priority `1`
#[no_mangle]
@ -151,9 +151,9 @@ mod app {
const RQ1_CEILING: u8 = 2;
// used to track how many more `bar` messages can be enqueued
// `U2` is the capacity of the `bar` task; a max of two instances can be queued
// `3-1=2` represents the capacity of this queue
// this queue is filled by the framework before `init` runs
static mut bar_FQ: Queue<(), U2> = Queue::new();
static mut bar_FQ: Queue<(), 3> = Queue::new();
// Priority ceiling for the consumer endpoint of `bar_FQ`
const bar_FQ_CEILING: u8 = 2;
@ -227,7 +227,7 @@ mod app {
// the free queue: used to track free slots in the `baz_INPUTS` array
// this queue is initialized with values `0` and `1` before `init` is executed
static mut baz_FQ: Queue<u8, U2> = Queue::new();
static mut baz_FQ: Queue<u8, 3> = Queue::new();
// Priority ceiling for the consumer endpoint of `baz_FQ`
const baz_FQ_CEILING: u8 = 2;

2
book/en/src/migration.md
View file

@ -1,4 +1,4 @@
# Migration Guides
This section describes how to migrate between different version of RTIC.
This section describes how to migrate between different versions of RTIC.
It also acts as a comparing reference between versions.

76
book/en/src/migration/migration_v4.md
View file

@ -1,19 +1,31 @@
# Migrating from v0.4.x to v0.5.0
This section covers how to upgrade an application written against RTIC v0.4.x to
This section covers how to upgrade an application written against RTFM v0.4.x to
the version v0.5.0 of the framework.
## Project name change RTFM -> RTIC
With release [v0.5.2][rtic0.5.2] the name was change to Real-Time Interrupt-driven Concurrency
All occurrences of `RTFM` needs to change to `RTIC`.
See [migration guide RTFM to RTIC](./migration_rtic.md)
[rtic0.5.2]: https://crates.io/crates/cortex-m-rtic/0.5.2
## `Cargo.toml`
First, the version of the `cortex-m-rtic` dependency needs to be updated to
`"0.5.0"`. The `timer-queue` feature needs to be removed.
Change the version of `cortex-m-rtfm` to
`"0.5.0"`, change `rtfm` to `rtic`.
Remove the `timer-queue` feature.
``` toml
[dependencies.cortex-m-rtic]
[dependencies.cortex-m-rtfm]
# change this
version = "0.4.3"
# into this
[dependencies.cortex-m-rtic]
version = "0.5.0"
# and remove this Cargo feature
@ -23,15 +35,15 @@ features = ["timer-queue"]
## `Context` argument
All functions inside the `#[rtic::app]` item need to take as first argument a
All functions inside the `#[rtfm::app]` item need to take as first argument a
`Context` structure. This `Context` type will contain the variables that were
magically injected into the scope of the function by version v0.4.x of the
framework: `resources`, `spawn`, `schedule` -- these variables will become
fields of the `Context` structure. Each function within the `#[rtic::app]` item
fields of the `Context` structure. Each function within the `#[rtfm::app]` item
gets a different `Context` type.
``` rust
#[rtic::app(/* .. */)]
#[rtfm::app(/* .. */)]
const APP: () = {
// change this
#[task(resources = [x], spawn = [a], schedule = [b])]
@ -75,11 +87,11 @@ const APP: () = {
## Resources
The syntax used to declare resources has been changed from `static mut`
The syntax used to declare resources has changed from `static mut`
variables to a `struct Resources`.
``` rust
#[rtic::app(/* .. */)]
#[rtfm::app(/* .. */)]
const APP: () = {
// change this
static mut X: u32 = 0;
@ -101,13 +113,13 @@ const APP: () = {
If your application was accessing the device peripherals in `#[init]` through
the `device` variable then you'll need to add `peripherals = true` to the
`#[rtic::app]` attribute to continue to access the device peripherals through
`#[rtfm::app]` attribute to continue to access the device peripherals through
the `device` field of the `init::Context` structure.
Change this:
``` rust
#[rtic::app(/* .. */)]
#[rtfm::app(/* .. */)]
const APP: () = {
#[init]
fn init() {
@ -121,7 +133,7 @@ const APP: () = {
Into this:
``` rust
#[rtic::app(/* .. */, peripherals = true)]
#[rtfm::app(/* .. */, peripherals = true)]
// ^^^^^^^^^^^^^^^^^^
const APP: () = {
#[init]
@ -137,13 +149,14 @@ const APP: () = {
## `#[interrupt]` and `#[exception]`
The `#[interrupt]` and `#[exception]` attributes have been removed. To declare
hardware tasks in v0.5.x use the `#[task]` attribute with the `binds` argument.
Remove the attributes `#[interrupt]` and `#[exception]`.
To declare hardware tasks in v0.5.x use the `#[task]`
attribute with the `binds` argument instead.
Change this:
``` rust
#[rtic::app(/* .. */)]
#[rtfm::app(/* .. */)]
const APP: () = {
// hardware tasks
#[exception]
@ -163,7 +176,7 @@ const APP: () = {
Into this:
``` rust
#[rtic::app(/* .. */)]
#[rtfm::app(/* .. */)]
const APP: () = {
#[task(binds = SVCall)]
// ^^^^^^^^^^^^^^
@ -183,25 +196,26 @@ const APP: () = {
## `schedule`
The `schedule` API no longer requires the `timer-queue` cargo feature, which has
been removed. To use the `schedule` API one must
first define the monotonic timer the runtime will use using the `monotonic`
argument of the `#[rtic::app]` attribute. To continue using the cycle counter
(CYCCNT) as the monotonic timer, and match the behavior of version v0.4.x, add
the `monotonic = rtic::cyccnt::CYCCNT` argument to the `#[rtic::app]` attribute.
The `schedule` API no longer requires the `timer-queue` cargo feature.
To use the `schedule` API one must first define the monotonic timer the
runtime will use using the `monotonic` argument of the `#[rtfm::app]` attribute.
To continue using the cycle counter (CYCCNT) as the monotonic timer,
and match the behavior of version v0.4.x, add the `monotonic = rtfm::cyccnt::CYCCNT`
argument to the `#[rtfm::app]` attribute.
Also, the `Duration` and `Instant` types and the `U32Ext` trait have been moved
into the `rtic::cyccnt` module. This module is only available on ARMv7-M+
devices. The removal of the `timer-queue` also brings back the `DWT` peripheral
inside the core peripherals struct, this will need to be enabled by the application
inside `init`.
Also, the `Duration` and `Instant` types and the `U32Ext` trait moved
into the `rtfm::cyccnt` module.
This module is only available on ARMv7-M+ devices.
The removal of the `timer-queue` also brings back the `DWT` peripheral
inside the core peripherals struct, if `DWT` is required,
ensure it is enabled by the application inside `init`.
Change this:
``` rust
use rtic::{Duration, Instant, U32Ext};
use rtfm::{Duration, Instant, U32Ext};
#[rtic::app(/* .. */)]
#[rtfm::app(/* .. */)]
const APP: () = {
#[task(schedule = [b])]
fn a() {
@ -213,10 +227,10 @@ const APP: () = {
Into this:
``` rust
use rtic::cyccnt::{Duration, Instant, U32Ext};
use rtfm::cyccnt::{Duration, Instant, U32Ext};
// ^^^^^^^^
#[rtic::app(/* .. */, monotonic = rtic::cyccnt::CYCCNT)]
#[rtfm::app(/* .. */, monotonic = rtfm::cyccnt::CYCCNT)]
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
const APP: () = {
#[init]

277
book/en/src/migration/migration_v5.md
View file

@ -1,10 +1,10 @@
# Migrating from v0.5.x to v0.6.0
# Migrating from v0.5.x to v1.0.0
This section describes how to upgrade from v0.5.x to v0.6.0 of the RTIC framework.
This section describes how to upgrade from v0.5.x to v1.0.0 of the RTIC framework.
## `Cargo.toml` - version bump
Change the version of `cortex-m-rtic` to `"0.6.0"`.
Change the version of `cortex-m-rtic` to `"1.0.0"`.
## `mod` instead of `const`
@ -71,7 +71,7 @@ mod app {
}
```
## Move Dispatchers from `extern "C"` to app arguments.
## Move Dispatchers from `extern "C"` to app arguments
Change
@ -102,6 +102,180 @@ mod app {
This works also for ram functions, see examples/ramfunc.rs
## Resources structs - `#[shared]`, `#[local]`
Previously the RTIC resources had to be in in a struct named exactly "Resources":
``` rust
struct Resources {
// Resources defined in here
}
```
With RTIC v1.0.0 the resources structs are annotated similarly like
`#[task]`, `#[init]`, `#[idle]`: with the attributes `#[shared]` and `#[local]`
``` rust
#[shared]
struct MySharedResources {
// Resources shared between tasks are defined here
}
#[local]
struct MyLocalResources {
// Resources defined here cannot be shared between tasks; each one is local to a single task
}
```
These structs can be freely named by the developer.
## `shared` and `local` arguments in `#[task]`s
In v1.0.0 resources are split between `shared` resources and `local` resources.
`#[task]`, `#[init]` and `#[idle]` no longer have a `resources` argument; they must now use the `shared` and `local` arguments.
In v0.5.x:
``` rust
struct Resources {
local_to_b: i64,
shared_by_a_and_b: i64,
}
#[task(resources = [shared_by_a_and_b])]
fn a(_: a::Context) {}
#[task(resources = [shared_by_a_and_b, local_to_b])]
fn b(_: b::Context) {}
```
In v1.0.0:
``` rust
#[shared]
struct Shared {
shared_by_a_and_b: i64,
}
#[local]
struct Local {
local_to_b: i64,
}
#[task(shared = [shared_by_a_and_b])]
fn a(_: a::Context) {}
#[task(shared = [shared_by_a_and_b], local = [local_to_b])]
fn b(_: b::Context) {}
```
## Symmetric locks
Now RTIC utilizes symmetric locks, this means that the `lock` method need
to be used for all `shared` resource access.
In old code one could do the following as the high priority
task has exclusive access to the resource:
``` rust
#[task(priority = 2, resources = [r])]
fn foo(cx: foo::Context) {
cx.resources.r = /* ... */;
}
#[task(resources = [r])]
fn bar(cx: bar::Context) {
cx.resources.r.lock(|r| r = /* ... */);
}
```
And with symmetric locks one needs to use locks in both tasks:
``` rust
#[task(priority = 2, shared = [r])]
fn foo(cx: foo::Context) {
cx.shared.r.lock(|r| r = /* ... */);
}
#[task(shared = [r])]
fn bar(cx: bar::Context) {
cx.shared.r.lock(|r| r = /* ... */);
}
```
Note that the performance does not change thanks to LLVM's optimizations which optimizes away unnecessary locks.
## Lock-free resource access
In RTIC 0.5 resources shared by tasks running at the same priority could be accessed *without* the `lock` API.
This is still possible in 1.0: the `#[shared]` resource must be annotated with the field-level `#[lock_free]` attribute.
v0.5 code:
``` rust
struct Resources {
counter: u64,
}
#[task(resources = [counter])]
fn a(cx: a::Context) {
*cx.resources.counter += 1;
}
#[task(resources = [counter])]
fn b(cx: b::Context) {
*cx.resources.counter += 1;
}
```
v1.0 code:
``` rust
#[shared]
struct Shared {
#[lock_free]
counter: u64,
}
#[task(shared = [counter])]
fn a(cx: a::Context) {
*cx.shared.counter += 1;
}
#[task(shared = [counter])]
fn b(cx: b::Context) {
*cx.shared.counter += 1;
}
```
## no `static mut` transform
`static mut` variables are no longer transformed to safe `&'static mut` references.
Instead of that syntax, use the `local` argument in `#[init]`.
v0.5.x code:
``` rust
#[init]
fn init(_: init::Context) {
static mut BUFFER: [u8; 1024] = [0; 1024];
let buffer: &'static mut [u8; 1024] = BUFFER;
}
```
v1.0.0 code:
``` rust
#[init(local = [
buffer: [u8; 1024] = [0; 1024]
// type ^^^^^^^^^^^^ ^^^^^^^^^ initial value
])]
fn init(cx: init::Context) -> (Shared, Local, init::Monotonics) {
let buffer: &'static mut [u8; 1024] = cx.local.buffer;
(Shared {}, Local {}, init::Monotonics())
}
```
## Init always returns late resources
In order to make the API more symmetric the #[init]-task always returns a late resource.
@ -125,53 +299,27 @@ to this:
``` rust
#[rtic::app(device = lm3s6965)]
mod app {
#[shared]
struct MySharedResources {}
#[local]
struct MyLocalResources {}
#[init]
fn init(_: init::Context) -> (init::LateResources, init::Monotonics) {
fn init(_: init::Context) -> (MySharedResources, MyLocalResources, init::Monotonics) {
rtic::pend(Interrupt::UART0);
(init::LateResources {}, init::Monotonics())
(MySharedResources, MyLocalResources, init::Monotonics())
}
// [more code]
}
```
## Resources struct - `#[resources]`
Previously the RTIC resources had to be in in a struct named exactly "Resources":
``` rust
struct Resources {
// Resources defined in here
}
```
With RTIC v0.6.0 the resources struct is annotated similarly like
`#[task]`, `#[init]`, `#[idle]`: with an attribute `#[resources]`
``` rust
#[resources]
struct Resources {
// Resources defined in here
}
```
In fact, the name of the struct is now up to the developer:
``` rust
#[resources]
struct Whateveryouwant {
// Resources defined in here
}
```
would work equally well.
## Spawn/schedule from anywhere
With the new "spawn/schedule from anywhere", old code such as:
## Spawn from anywhere
With the new spawn/spawn_after/spawn_at interface,
old code requiring the context `cx` for spawning such as:
``` rust
#[task(spawn = [bar])]
@ -195,43 +343,20 @@ fn foo(_c: foo::Context) {
#[task]
fn bar(_c: bar::Context) {
foo::schedule(/* ... */).unwrap();
// Takes a Duration, relative to “now”
let spawn_handle = foo::spawn_after(/* ... */);
}
#[task]
fn bar(_c: bar::Context) {
// Takes an Instant
let spawn_handle = foo::spawn_at(/* ... */);
}
```
Note that the attributes `spawn` and `schedule` are no longer needed.
Thus the requirement of having access to the context is dropped.
## Symmetric locks
Now RTIC utilizes symmetric locks, this means that the `lock` method need to be used for all resource access. In old code one could do the following as the high priority task has exclusive access to the resource:
``` rust
#[task(priority = 2, resources = [r])]
fn foo(cx: foo::Context) {
cx.resources.r = /* ... */;
}
#[task(resources = [r])]
fn bar(cx: bar::Context) {
cx.resources.r.lock(|r| r = /* ... */);
}
```
And with symmetric locks one needs to use locks in both tasks:
``` rust
#[task(priority = 2, resources = [r])]
fn foo(cx: foo::Context) {
cx.resources.r.lock(|r| r = /* ... */);
}
#[task(resources = [r])]
fn bar(cx: bar::Context) {
cx.resources.r.lock(|r| r = /* ... */);
}
```
Note that the performance does not change thanks to LLVM's optimizations which optimizes away unnecessary locks.
Note that the attributes `spawn`/`schedule` in the task definition are no longer needed.
---
@ -239,7 +364,9 @@ Note that the performance does not change thanks to LLVM's optimizations which o
### Extern tasks
Both software and hardware tasks can now be defined external to the `mod app`. Previously this was possible only by implementing a trampoline calling out the task implementation.
Both software and hardware tasks can now be defined external to the `mod app`.
Previously this was possible only by implementing a trampoline calling out the task implementation.
See examples `examples/extern_binds.rs` and `examples/extern_spawn.rs`.
This enables breaking apps into multiple files.

155
book/en/src/preface.md
View file

@ -1,26 +1,161 @@
<div align="center"><img width="300" height="300" src="RTIC.svg"></div>
<div style="font-size: 6em; font-weight: bolder;" align="center">RTIC</div>
<h1 align="center">Real-Time Interrupt-driven Concurrency</h1>
<h1 align="center">The hardware accelerated Rust RTOS</h1>
<p align="center">A concurrency framework for building real-time systems</p>
# Preface
This book contains user level documentation for the Real-Time Interrupt-driven Concurrency
(RTIC) framework. The API reference can be found [here](../../api/).
(RTIC) framework. The API reference is available [here](../../api/).
Formerly known as Real-Time For the Masses.
This is the documentation for RTIC v2.x.
<!--There is a translation of this book in [Russian].-->
Older releases:
[RTIC v1.x](/1.0) | [RTIC v0.5.x (unsupported)](/0.5) | [RTFM v0.4.x (unsupported)](/0.4)
<!--[Russian]: ../ru/index.html-->
{{#include ../../../README.md:7:12}}
This is the documentation of v0.6.x of RTIC; for the documentation of version
## Is RTIC an RTOS?
* v0.5.x go [here](/0.5).
* v0.4.x go [here](/0.4).
A common question is whether RTIC is an RTOS or not, and depending on your background the answer may vary. From RTIC's developers point of view; RTIC is a hardware accelerated RTOS that utilizes the hardware such as the NVIC on Cortex-M MCUs, CLIC on RISC-V etc. to perform scheduling, rather than the more classical software kernel.
{{#include ../../../README.md:7:46}}
Another common view from the community is that RTIC is a concurrency framework as there
is no software kernel and that it relies on external HALs.
{{#include ../../../README.md:52:}}
## RTIC - The Past, current and Future
This section gives a background to the RTIC model. Feel free to skip to section [RTIC the model](preface.md#rtic-the-model) for a TL;DR.
The RTIC framework takes the outset from real-time systems research at Luleå University of Technology (LTU) Sweden. RTIC is inspired by the concurrency model of the [Timber] language, the [RTFM-SRP] based scheduler, the [RTFM-core] language and [Abstract Timer] implementation. For a full list of related research see [TODO].
[Timber]: https://timber-lang.org/
[RTFM-SRP]: https://www.diva-portal.org/smash/get/diva2:1005680/FULLTEXT01.pdf
[RTFM-core]: https://ltu.diva-portal.org/smash/get/diva2:1013248/FULLTEXT01.pdf
[Abstract Timer]: https://ltu.diva-portal.org/smash/get/diva2:1013030/FULLTEXT01.pdf
## Stack Resource Policy based Scheduling
[Stack Resource Policy (SRP)][SRP] based concurrency and resource management is at heart of the RTIC framework. The SRP model itself extends on [Priority Inheritance Protocols], and provides a set of outstanding properties for single core scheduling. To name a few:
- preemptive deadlock and race-free scheduling
- resource efficiency
- tasks execute on a single shared stack
- tasks run-to-completion with wait free access to shared resources
- predictable scheduling, with bounded priority inversion by a single (named) critical section
- theoretical underpinning amenable to static analysis (e.g., for task response times and overall schedulability)
SRP comes with a set of system-wide requirements:
- each task is associated a static priority,
- tasks execute on a single-core,
- tasks must be run-to-completion, and
- resources must be claimed/locked in LIFO order.
[SRP]: https://link.springer.com/article/10.1007/BF00365393
[Priority Inheritance Protocols]: https://ieeexplore.ieee.org/document/57058
## SRP analysis
SRP based scheduling requires the set of static priority tasks and their access to shared resources to be known in order to compute a static *ceiling* (𝝅) for each resource. The static resource *ceiling* 𝝅(r) reflects the maximum static priority of any task that accesses the resource `r`.
### Example
Assume two tasks `A` (with priority `p(A) = 2`) and `B` (with priority `p(B) = 4`) both accessing the shared resource `R`. The static ceiling of `R` is 4 (computed from `𝝅(R) = max(p(A) = 2, p(B) = 4) = 4`).
A graph representation of the example:
```mermaid
graph LR
A["p(A) = 2"] --> R
B["p(A) = 4"] --> R
R["𝝅(R) = 4"]
```
## RTIC the hardware accelerated real-time scheduler
SRP itself is compatible with both dynamic and static priority scheduling. For the implementation of RTIC we leverage on the underlying hardware for accelerated static priority scheduling.
In the case of the `ARM Cortex-M` architecture, each interrupt vector entry `v[i]` is associated a function pointer (`v[i].fn`), and a static priority (`v[i].priority`), an enabled- (`v[i].enabled`) and a pending-bit (`v[i].pending`).
An interrupt `i` is scheduled (run) by the hardware under the conditions:
1. is `pended` and `enabled` and has a priority higher than the (optional `BASEPRI`) register, and
1. has the highest priority among interrupts meeting 1.
The first condition (1) can be seen a filter allowing RTIC to take control over which tasks should be allowed to start (and which should be prevented from starting).
The SPR model for single-core static scheduling on the other hand states that a task should be scheduled (run) under the conditions:
1. it is `requested` to run and has a static priority higher than the current system ceiling (𝜫)
1. it has the highest static priority among tasks meeting 1.
The similarities are striking and it is not by chance/luck/coincidence. The hardware was cleverly designed with real-time scheduling in mind.
In order to map the SRP scheduling onto the hardware we need to take a closer look at the system ceiling (𝜫). Under SRP 𝜫 is computed as the maximum priority ceiling of the currently held resources, and will thus change dynamically during the system operation.
## Example
Assume the task model above. Starting from an idle system, 𝜫 is 0, (no task is holding any resource). Assume that `A` is requested for execution, it will immediately be scheduled. Assume that `A` claims (locks) the resource `R`. During the claim (lock of `R`) any request `B` will be blocked from starting (by 𝜫 = `max(𝝅(R) = 4) = 4`, `p(B) = 4`, thus SRP scheduling condition 1 is not met).
## Mapping
The mapping of static priority SRP based scheduling to the Cortex M hardware is straightforward:
- each task `t` are mapped to an interrupt vector index `i` with a corresponding function `v[i].fn = t` and given the static priority `v[i].priority = p(t)`.
- the current system ceiling is mapped to the `BASEPRI` register or implemented through masking the interrupt enable bits accordingly.
## Example
For the running example, a snapshot of the ARM Cortex M [Nested Vectored Interrupt Controller (NVIC)][NVIC] may have the following configuration (after task `A` has been pended for execution.)
| Index | Fn | Priority | Enabled | Pended |
| ----- | --- | -------- | ------- | ------ |
| 0 | A | 2 | true | true |
| 1 | B | 4 | true | false |
[NVIC]: https://developer.arm.com/documentation/ddi0337/h/nested-vectored-interrupt-controller/about-the-nvic
(As discussed later, the assignment of interrupt and exception vectors is up to the user.)
A claim (lock(r)) will change the current system ceiling (𝜫) and can be implemented as a *named* critical section:
- old_ceiling = 𝜫, 𝜫 = 𝝅(r)
- execute code within critical section
- old_ceiling = 𝜫
This amounts to a resource protection mechanism requiring only two machine instructions on enter and one on exit the critical section for managing the `BASEPRI` register. For architectures lacking `BASEPRI`, we can implement the system ceiling through a set of machine instructions for disabling/enabling interrupts on entry/exit for the named critical section. The number of machine instructions vary depending on the number of mask registers that needs to be updated (a single machine operation can operate on up to 32 interrupts, so for the M0/M0+ architecture a single instruction suffice). RTIC will determine the ceiling values and masking constants at compile time, thus all operations is in Rust terms zero-cost.
In this way RTIC fuses SRP based preemptive scheduling with a zero-cost hardware accelerated implementation, resulting in "best in class" guarantees and performance.
Given that the approach is dead simple, how come SRP and hardware accelerated scheduling is not adopted by any other mainstream RTOS?
The answer is simple, the commonly adopted threading model does not lend itself well to static analysis - there is no known way to extract the task/resource dependencies from the source code at compile time (thus ceilings cannot be efficiently computed and the LIFO resource locking requirement cannot be ensured). Thus, SRP based scheduling is in the general case out of reach for any thread based RTOS.
## RTIC into the Future
Asynchronous programming in various forms are getting increased popularity and language support. Rust natively provides an `async`/`await` API for cooperative multitasking and the compiler generates the necessary boilerplate for storing and retrieving execution contexts (i.e., managing the set of local variables that spans each `await`).
The Rust standard library provides collections for dynamically allocated data-structures which are useful to manage execution contexts at run-time. However, in the setting of resource constrained real-time systems, dynamic allocations are problematic (both regarding performance and reliability - Rust runs into a *panic* on an out-of-memory condition). Thus, static allocation is the preferable approach!
RTIC provides a mechanism for `async`/`await` that relies solely on static allocations. However, the implementation relies on the `#![feature(type_alias_impl_trait)]` (TAIT) which is undergoing stabilization (thus RTIC v2.x currently requires a *nightly* toolchain). Technically, using TAIT, the compiler determines the size of each execution context allowing static allocation.
From a modelling perspective `async/await` lifts the run-to-completion requirement of SRP, and each section of code between two yield points (`await`s) can be seen as an individual task. The compiler will reject any attempt to `await` while holding a resource (not doing so would break the strict LIFO requirement on resource usage under SRP).
So with the technical stuff out of the way, what does `async/await` bring to the table?
The answer is - improved ergonomics! A recurring use case is to have task perform a sequence of requests and then await their results in order to progress. Without `async`/`await` the programmer would be forced to split the task into individual sub-tasks and maintain some sort of state encoding (and manually progress by selecting sub-task). Using `async/await` each yield point (`await`) essentially represents a state, and the progression mechanism is built automatically for you at compile time by means of `Futures`.
Rust `async`/`await` support is still incomplete and/or under development (e.g., there are no stable way to express `async` closures, precluding use in iterator patterns). Nevertheless, Rust `async`/`await` is production ready and covers most common use cases.
An important property is that futures are composable, thus you can await either, all, or any combination of possible futures (allowing e.g., timeouts and/or asynchronous errors to be promptly handled). For more details and examples see Section [todo].
## RTIC the model
An RTIC `app` is a declarative and executable system model for single-core applications, defining a set of (`local` and `shared`) resources operated on by a set of (`init`, `idle`, *hardware* and *software*) tasks. In short the `init` task runs before any other task returning a set of resources (`local` and `shared`). Tasks run preemptively based on their associated static priority, `idle` has the lowest priority (and can be used for background work, and/or to put the system to sleep until woken by some event). Hardware tasks are bound to underlying hardware interrupts, while software tasks are scheduled by asynchronous executors (one for each software task priority).
At compile time the task/resource model is analyzed under SRP and executable code generated with the following outstanding properties:
- guaranteed race-free resource access and deadlock-free execution on a single-shared stack (thanks to SRP)
- hardware task scheduling is performed directly by the hardware, and
- software task scheduling is performed by auto generated async executors tailored to the application.
The RTIC API design ensures that both SRP requirements and Rust soundness rules are upheld at all times, thus the executable model is correct by construction. Overall, the generated code infers no additional overhead in comparison to a handwritten implementation, thus in Rust terms RTIC offers a zero-cost abstraction to concurrency.

33
book/en/src/rtic_vs.md Normal file
View file

@ -0,0 +1,33 @@
# RTIC vs. the world
RTIC aims to provide the lowest level of abstraction needed for developing robust and reliable embedded software.
It provides a minimal set of required mechanisms for safe sharing of mutable resources among interrupts and asynchronously executing tasks. The scheduling primitives leverages on the underlying hardware for unparalleled performance and predictability, in effect RTIC provides in Rust terms a zero-cost abstraction to concurrent real-time programming.
## Comparison regarding safety and security
Comparing RTIC to traditional a Real-Time Operating System (RTOS) is hard. Firstly, a traditional RTOS typically comes with no guarantees regarding system safety, even the most hardened kernels like the formally verified [seL4] kernel. Their claims to integrity, confidentiality, and availability regards only the kernel itself (under additional assumptions its configuration and environment). They even state:
"An OS kernel, verified or not, does not automatically make a system secure. In fact, any system, no matter how secure, can be used in insecure ways." - [seL4 FAQ][sel4faq]
[sel4faq]: https://docs.sel4.systems/projects/sel4/frequently-asked-questions.html
[seL4]: https://sel4.systems/
### Security by design
In the world of information security we commonly find:
- confidentiality, protecting the information from being exposed to an unauthorized party,
- integrity, referring to accuracy and completeness of data, and
- availability, referring to data being accessible to authorized users.
Obviously, a traditional OS can guarantee neither confidentiality nor integrity, as both requires the security critical code to be trusted. Regarding availability, this typically boils down to the usage of system resources. Any OS that allows for dynamic allocation of resources, relies on that the application correctly handles allocations/de-allocations, and cases of allocation failures.
Thus their claim is correct, security is completely out of hands for the OS, the best we can hope for is that it does not add further vulnerabilities.
RTIC on the other hand holds your back. The declarative system wide model gives you a static set of tasks and resources, with precise control over what data is shared and between which parties. Moreover, Rust as a programming language comes with strong properties regarding integrity (compile time aliasing, mutability and lifetime guarantees, together with ensured data validity).
Using RTIC these properties propagate to the system wide model, without interference of other applications running. The RTIC kernel is internally infallible without any need of dynamically allocated data.

9
book/ru/book.toml
View file

@ -1,9 +0,0 @@
[book]
authors = ["Jorge Aparicio, Per Lindgren and The Real-Time Interrupt-driven Concurrency developers"]
multilingual = false
src = "src"
title = "Real-Time Interrupt-driven Concurrency"
[output.html]
git-repository-url = "https://github.com/rtic-rs/cortex-m-rtic"
git-repository-icon = "fa-github"

109
book/ru/src/RTIC.svg
View file

@ -1,109 +0,0 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
inkscape:version="1.0.1 (3bc2e813f5, 2020-09-07)"
inkscape:export-ydpi="145.74001"
inkscape:export-xdpi="145.74001"
inkscape:export-filename="/home/emifre/Documents/logo/v2_seller1/vctr/g248_2.png"
sodipodi:docname="RTIC.svg"
viewBox="0 0 375.55994 408.84339"
height="408.84338"
width="375.55994"
xml:space="preserve"
id="svg2"
version="1.1"><metadata
id="metadata8"><rdf:RDF><cc:Work
rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" /><dc:title></dc:title></cc:Work></rdf:RDF></metadata><defs
id="defs6"><clipPath
id="clipPath18"
clipPathUnits="userSpaceOnUse"><path
id="path16"
d="M 0,500 H 500 V 0 H 0 Z" /></clipPath></defs><sodipodi:namedview
inkscape:current-layer="g10"
inkscape:window-maximized="1"
inkscape:window-y="0"
inkscape:window-x="0"
inkscape:cy="229.27385"
inkscape:cx="150.39187"
inkscape:zoom="1.5119999"
fit-margin-bottom="0"
fit-margin-right="0"
fit-margin-left="0"
fit-margin-top="0"
inkscape:pagecheckerboard="false"
showgrid="false"
id="namedview4"
inkscape:window-height="1016"
inkscape:window-width="1920"
inkscape:pageshadow="2"
inkscape:pageopacity="0"
guidetolerance="10"
gridtolerance="10"
objecttolerance="10"
borderopacity="1"
bordercolor="#666666"
pagecolor="#ffffff"
inkscape:document-rotation="0" /><g
transform="matrix(1.3333333,0,0,-1.3333333,-148.85309,622.34951)"
inkscape:label="45453_RTIC logo_JK"
inkscape:groupmode="layer"
id="g10"><g
inkscape:export-filename="/home/emifre/Documents/logo/v2_seller1/vctr/g248.png"
inkscape:export-ydpi="153.37898"
inkscape:export-xdpi="153.37898"
style="opacity:1;fill:#4d4d4d;fill-opacity:1"
transform="matrix(7.464224,0,0,7.464224,393.30978,300.96457)"
id="g248"><path
id="path250"
style="fill:#4d4d4d;fill-opacity:1;fill-rule:nonzero;stroke:none"
d="m 0,0 c 0,-10.421 -8.448,-18.868 -18.868,-18.868 -10.421,0 -18.868,8.447 -18.868,18.868 0,10.421 8.447,18.868 18.868,18.868 C -8.448,18.868 0,10.421 0,0" /></g><g
inkscape:export-filename="/home/emifre/Documents/logo/v2_seller1/vctr/g248.png"
inkscape:export-ydpi="153.37898"
inkscape:export-xdpi="153.37898"
transform="matrix(7.464224,0,0,7.464224,292.89574,388.12804)"
id="g252"><path
sodipodi:nodetypes="cccccccccc"
id="path254"
style="fill:#cccccc;fill-opacity:1;fill-rule:nonzero;stroke:none"
d="M 0,0 C -0.604,5.477 -5.967,9.765 -6.856,10.442 -6.487,9.748 -5.71,8.123 -5.267,6.023 -4.92,4.374 -4.845,2.758 -5.043,1.221 -5.291,-0.701 -5.97,-2.505 -7.062,-4.14 c -0.294,-0.441 -0.601,-0.894 -0.926,-1.374 -3.428,-5.065 -8.25205,-11.907209 -7.04305,-17.843209 0.528,-2.592 2.166,-4.805 4.866,-6.583 -7.606,6.593 -2.20795,13.944209 1.62005,17.105209 C -5.253,-10.117 0.659,-5.974 0,0" /></g><g
inkscape:export-filename="/home/emifre/Documents/logo/v2_seller1/vctr/g248.png"
inkscape:export-ydpi="153.37898"
inkscape:export-xdpi="153.37898"
transform="matrix(7.464224,0,0,7.464224,193.42458,186.62982)"
id="g256"><path
sodipodi:nodetypes="ccccccccccc"
id="path258"
style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none"
d="m 0,0 c -0.777,1.074 -1.303,2.263 -1.562,3.535 -1.212,5.951 3.488,12.895 6.92,17.966 0.325,0.48 0.632,0.933 0.926,1.374 2.464,3.693 2.333,7.549 1.789,10.135 -0.456,2.168 -1.27,3.828 -1.621,4.477 -0.038,0.028 -0.058,0.043 -0.058,0.043 0,0 -6.038,-7.951 -8.738,-12.258 C -5.045,20.964 -8.509,12.81 -5.274,5.863 -2.263,-0.605 2.4913395,-2.6700085 3.1613395,-2.9450085 1.7523395,-2.0240085 0.824,-1.138 0,0" /></g><g
inkscape:export-filename="/home/emifre/Documents/logo/v2_seller1/vctr/g248.png"
inkscape:export-ydpi="153.37898"
inkscape:export-xdpi="153.37898"
transform="matrix(7.464224,0,0,7.464224,286.22601,210.85049)"
id="g260"><path
sodipodi:nodetypes="cccccccssc"
id="path262"
style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none"
d="m 0,0 c -0.199,-4.847 -3.7433301,-6.7788234 -3.7433301,-6.7788234 0,0 0.2005158,0.00584 0.4557728,0.023109 C -0.01255733,-5.7517164 4.496,-3.342 4.518,2.624 4.53,5.687 2.682,7.663 1.13,8.781 c -1.149,0.828 -2.309,1.321 -2.935,1.551 -0.396,-0.067 -2.392,-0.519 -2.51,-2.836 0,0 -3.5425677,-1.2008654 -3.56,-1.632 C -7.9046856,5.1298176 -6.9355723,4.1874599 -6.187,3.63 -5.1908601,2.8881772 0.199,4.847 0,0" /></g><g
inkscape:export-filename="/home/emifre/Documents/logo/v2_seller1/vctr/g248.png"
inkscape:export-ydpi="153.37898"
inkscape:export-xdpi="153.37898"
transform="matrix(7.464224,0,0,7.464224,360.6426,228.88853)"
id="g264"><path
sodipodi:nodetypes="zcccccccccccczzz"
id="path266"
style="fill:#cccccc;fill-opacity:1;fill-rule:nonzero;stroke:none"
d="M -0.34917151,1.6816738 C -0.7974951,5.9368052 -3.1264734,7.1611735 -5.072,8.56 c 0,0 -0.8516082,3.022335 -1.7015402,3.1237 0,0 0.3570815,0.04169 0,0 -0.6687287,0.05444 -1.1522423,-0.270149 -1.9532423,-1.364149 0,0 -1.1502065,1.167917 -2.4848885,1.093235 C -12.505303,11.107968 -11.817,7.957 -11.818,7.928 c 0.64,-0.24 1.768,-0.729 2.886,-1.535 0.992,-0.715 1.781,-1.534 2.346,-2.437 0.707,-1.128 1.062,-2.389 1.057,-3.748 -0.006,-1.773 -0.433,-3.369 -1.267,-4.743 -0.712,-1.172 -1.724,-2.193 -3.01,-3.036 -1.181,-0.774 -2.329326,-1.2453139 -3.451326,-1.6013139 1.173268,0.050293 3.778241,0.431572 5.8646425,1.3359556 2.0864016,0.9043837 3.5682459,1.7417342 4.4081274,2.592566 0.8398814,0.8508318 3.08370818,2.6703347 2.63538459,6.9254661 z" /></g><path
inkscape:export-filename="/home/emifre/Documents/logo/v2_seller1/vctr/g248.png"
sodipodi:nodetypes="ssss"
inkscape:export-ydpi="153.37898"
inkscape:export-xdpi="153.37898"
id="path1340"
d="m 227.38125,254.73726 c -0.52355,-1.50734 0.39304,-4.38366 2.33326,-6.47436 2.23581,-2.40923 7.33976,11.89073 4.18714,10.96111 -2.21547,-0.65328 -6.03712,-3.09534 -6.5204,-4.48675 z"
style="fill:#808080;fill-opacity:1;stroke:#cccccc;stroke-width:0;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" /></g></svg>
Side by side

Before

Width:  |  Height:  |  Size: 6.8 KiB

25
book/ru/src/SUMMARY.md
View file

@ -1,25 +0,0 @@
# Summary
[Введение](./preface.md)
- [RTIC в примерах](./by-example.md)
- [Атрибут `app`](./by-example/app.md)
- [Ресурсы](./by-example/resources.md)
- [Программные задачи](./by-example/tasks.md)
- [Очередь таймера](./by-example/timer-queue.md)
- [Типы, Send и Sync](./by-example/types-send-sync.md)
- [Создание нового проекта](./by-example/new.md)
- [Советы и хитрости](./by-example/tips.md)
- [Инструкции по миграции](./migration.md)
- [v0.5.x на v0.6.x](./migration/migration_v5.md)
- [v0.4.x на v0.5.x](./migration/migration_v4.md)
- [RTFM на RTIC](./migration/migration_rtic.md)
- [Под капотом](./internals.md)
- [Настройка прерываний](./internals/interrupt-configuration.md)
- [Нереентерабельнось](./internals/non-reentrancy.md)
- [Контроль доступа](./internals/access.md)
- [Поздние ресурсы](./internals/late-resources.md)
- [Критические секции](./internals/critical-sections.md)
- [Анализ приоритетов](./internals/ceilings.md)
- [Программные задачи](./internals/tasks.md)
- [Очередь таймера](./internals/timer-queue.md)

23
book/ru/src/by-example.md
View file

@ -1,23 +0,0 @@
# RTIC в примерах
В этой части книги фреймворк Real-Time Interrupt-driven Concurrency (RTIC) представляется
новым пользователям путем прохода по примерам от простых к более сложным.
Все примеры в этой части книги можно найти в [репозитарии] проекта.
Большинство из них можно пройти, запустив их на эмуляторе QEMU без специального оборудования.
[репозитарии]: https://github.com/rtic-rs/cortex-m-rtic
Для запуска примеров на вашем ПК, вам понадобится программа `qemu-system-arm`.
В [the embedded Rust book] есть инструкции по настройке среды для эмбеддед разработке,
в том числе QEMU.
[the embedded Rust book]: https://rust-embedded.github.io/book/intro/install.html
## Примеры из реальной жизни
Ниже представлены примеры использования RTIC (RTFM) в реальных проектах.
### RTFM V0.4.2
- [etrombly/sandbox](https://github.com/etrombly/sandbox/tree/41d423bcdd0d8e42fd46b79771400a8ca349af55). Аппаратный дзэн-сад, рисующий картинки на песке. Картинки передаются по последовательному порту с помощью G-кода.

160
book/ru/src/by-example/app.md
View file

@ -1,160 +0,0 @@
# Атрибут `app`
Это простейшая из возможных программ на RTIC:
``` rust
{{#include ../../../../examples/smallest.rs}}
```
Все программы на RTIC используют атрибут [`app`] (`#[app(..)]`). Этот атрибут
должен применяться к элементу `mod`. Атрибут `app` имеет обязательный аргумент `device`,
который принимает *путь* как значение. Это должен быть полный путь, указывающий на
*крейт доступа к периферии* (PAC), сгенерированный с помощью [`svd2rust`] версии **v0.14.x**
или новее. Более подробно в разделе [Создание нового проекта](./new.md).
Атрибут `app` будет раскрыт в подходящую точку входа программы, поэтому
атрибут [`cortex_m_rt::entry`] не нужен.
[`app`]: ../../../api/cortex_m_rtic_macros/attr.app.html
[`svd2rust`]: https://crates.io/crates/svd2rust
[`cortex_m_rt::entry`]: ../../../api/cortex_m_rt_macros/attr.entry.html
## `init`
Внутри модуля `app` атрибут ожидает найти функцию инициализации, помеченную
атрибутом `init`. Эта функция должна иметь сигнатуру
`fn(init::Context) [-> init::LateResources]` (возвращаемый тип нужен не всегда).
Эта функция инициализации будет первой частью программы, выполняемой при запуске.
Функция `init` будет запущена *с отключенными прерываниями* и будет иметь эксклюзивный доступ
к Cortex-M, в котором токен `bare_metal::CriticalSection` доступен как `cs`.
Опционально, устройство-специфичные периферия доступна через поля `core` и `device` структуры
`init::Context`.
`static mut` переменные, определенные в начале `init` будут преобразованы в
`&'static mut` ссылки, безопасные для доступа. Обратите внимание, данная возможность может
быть удалена в следующем релизе, см. `task_local` ресурсы.
[`rtic::Peripherals`]: ../../api/rtic/struct.Peripherals.html
Пример ниже показывает типы полей `core`, `device` и `cs`, и демонстрирует
безопасный доступ к `static mut` переменной. Поле `device` доступно только
когда аргумент `peripherals` установлен в `true` (по умолчанию).
В редких случаях, когда вы захотите создать приложение с минимальным потреблением ресурсов,
можно явно установить `peripherals` в `false`.
``` rust
{{#include ../../../../examples/init.rs}}
```
Запуск примера напечатате `init` в консоли, а затем завершит процесс QEMU.
``` console
$ cargo run --example init
{{#include ../../../../ci/expected/init.run}}
```
## `idle`
Функцию, помеченную атрибутом `idle` может опционально добавить в модуль.
Эта функция используется как специальная *задача ожидания* и должна иметь сигнатуру
`fn(idle::Context) - > !`.
Если она присутствует, задача `idle` будет запущена после `init`. В отличие от
`init`, `idle` будет запущена *с включенными прерываниями* и она не может вернуть результат,
а значит должна работать вечно.
Если функция `idle` не определена, среда вполнения устанавливает бит [SLEEPONEXIT], а затем
отправляет микроконтроллер в сон после запуска `init`.
[SLEEPONEXIT]: https://developer.arm.com/docs/100737/0100/power-management/sleep-mode/sleep-on-exit-bit
Как и в `init`, `static mut` переменные будут трансформированы в `&'static mut` ссылки,
безопасные для доступа. Обратите внимание, данная возможность может
быть удалена в следующем релизе, см. `task_local` ресурсы.
Пример ниже показывает, что `idle` запускается после `init`.
**Примечание:** Цикл `loop {}` в функци ожидания не может быть пустым, так как это сломает
микроконтроллер, из-за того, что LLVM компилирует пустые циклы в инструкцию `UDF` в release mode.
Чтобы избежать неопределенного поведения, цикл должен включать "side-effect"
путем вставки ассемблерной инструкции (например, `WFI`) или ключевого слова `continue`.
``` rust
{{#include ../../../../examples/idle.rs}}
```
``` console
$ cargo run --example idle
{{#include ../../../../ci/expected/idle.run}}
```
## Аппаратные задачи
Чтобы объявить обработчик прерывания, фреймворк предоставляет атрибут `#[task]`,
который можно применять к функциям. Этот атрибут берет аргумент `binds`, чье значение -
это имя прерывания, которому будет назначен обработчик;
функция, декорированная этим атрибутом становится обработчиком прерывания.
В фреймворке такие типы задач именуются *аппаратными*, потому что они начинают
выполняться в ответ на аппаратное событие.
Пример ниже демонстрирует использование атрибута `#[task]`, чтобы объявить
обработчик прерывания. Как и в случае с `#[init]` и `#[idle]` локальные `static
mut` переменные безопасны для использования с аппаратной задачей.
``` rust
{{#include ../../../../examples/hardware.rs}}
```
``` console
$ cargo run --example hardware
{{#include ../../../../ci/expected/hardware.run}}
```
До сих пор все программы на RTIC, которые мы видели, не отличались от программ,
которые можно написать, используя лишь крейт `cortex-m-rt`. С этого момента мы
начинаем представлять возможности, уникальные для RTIC.
## Приоритеты
Статический приоритет каждого обработчика можно оределить в атрибуте `task`, используя
аргумент `priority`. Задачи могут иметь приоритет в диапазоне `1..=(1 << NVIC_PRIO_BITS)`,
где `NVIC_PRIO_BITS` - это константа, определенная в крейте `устройства`.
Когда аргумент `priority` не указан, предполагается, что приоритет равен `1`.
Задача `idle` имеет ненастраиваемый приоритет `0`, наименьший из возможных.
> Более высокое значение означает более высокий приоритет в RTIC, что противоположно тому,
> что указано в периферии NVIC Cortex-M.
> Точнее, это значит, что число `10` обозначает приоритет **выше**, чем число `9`.
Когда несколько задач готовы к запуску, задача с самым большим статическим
приоритетом будет запущена первой. Приоритезацию задач можно рассматривать по
такому сценарию: сигнал прерывания приходит во время выполнения задачи с низким приоритетом;
сигнал переключает задачу с высоким приоритетом в режим ожидания.
Разница в приоритетах приводи к тому, что задача с высоким приоритетом вытесняет задачу с низким:
выполнение задачи с низким приоритетом замораживается и задача с высоким приоритетом выполняется,
пока не будет завершена. Как только задача с высоким приоритетом будет остановлена,
продолжится выполнение задачи с низким приоритетом.
Следующий пример демонстрирует диспетчеризацию на основе приоритетов задач.
``` rust
{{#include ../../../../examples/preempt.rs}}
```
``` console
$ cargo run --example preempt
{{#include ../../../../ci/expected/preempt.run}}
```
Заметьте, что задача `gpiob` *не* вытесняет задачу `gpioc`, потому что ее приоритет
*такой же*, как и у `gpioc`. Однако, как только `gpioc` возвращает результат,
выполненяется задача `gpiob`, как более приоритетная по сравнению с `gpioa`.
Выполнение `gpioa` возобновляется только после выхода из `gpiob`.
Еще одно замечание по поводу приоритетов: выбор приоритета большего, чем поддерживает устройство
(а именно `1 << NVIC_PRIO_BITS`) приведет к ошибке компиляции.
Из-за ограничений языка, сообщение об ошибке далеко от понимания:
вам скажут что-то похожее на "evaluation of constant value failed", а указатель на ошибку
*не* покажет на проблемное значение прерывания --
мы извиняемся за это!

84
book/ru/src/by-example/new.md
View file

@ -1,84 +0,0 @@
# Создание нового проекта
Теперь, когда Вы изучили основные возможности фреймворка RTIC, Вы можете
попробовать его использовать на Вашем оборудовании следуя этим инструкциям.
1. Создайте экземпляр из шаблона [`cortex-m-quickstart`].
[`cortex-m-quickstart`]: https://github.com/rust-embedded/cortex-m-quickstart#cortex-m-quickstart
``` console
$ # например используя `cargo-generate`
$ cargo generate \
--git https://github.com/rust-embedded/cortex-m-quickstart \
--name app
$ # следуйте остальным инструкциям
```
2. Добавьте крейт доступа к периферии (PAC), сгенерированный с помощью[`svd2rust`]
**v0.14.x**, или крейт отладочной платы, у которой в зависимостях один из таких PAC'ов.
Убедитесь, что опция `rt` крейта включена.
[`svd2rust`]: https://crates.io/crates/svd2rust
В этом примере я буду использовать крейт устройства [`lm3s6965`].
Эта библиотека не имеет Cargo-опции `rt`; эта опция всегда включена.
[`lm3s6965`]: https://crates.io/crates/lm3s6965
Этот крейт устройства предоставляет линковочный скрипт с макетом памяти
целевого устройства, поэтому `memory.x` и `build.rs` нужно удалить.
``` console
$ cargo add lm3s6965 --vers 0.1.3
$ rm memory.x build.rs
```
3. Добавьте крейт `cortex-m-rtic` как зависимость.
``` console
$ cargo add cortex-m-rtic --allow-prerelease
```
4. Напишите свою RTIC программу.
Здесь я буду использовать пример `init` из крейта `cortex-m-rtic`.
Примеры находтся в папке `examples`, а содержание `init.rs` показано здесь:
``` console
{{#include ../../../../examples/init.rs}}
```
Пример `init` использует устройство `lm3s6965`. Не забудьте настроить аргумент `device`
в атрибуте макроса app так, чтобы он соответствовал пути к PAC-крейту, если он отличается,
а также добавить перифериб и другие аргументы если необходимо.
Несмотря на то, что в программе могут использоваться псевдонимы типов,
здесь необходимо указать полный путь (из корня крейта). Для многих устройств,
есть общий подход в крейтах реализации HAL (с псевдонимом `hal`) и крейтах поддержки
отладочных плат реекспортиорвать PAC как `pac`, что приводит нас к образцу, аналогичному
приведенному ниже:
```rust
use abcd123_hal as hal;
//...
#[rtic::app(device = crate::hal::pac, peripherals = true, monotonic = rtic::cyccnt::CYCCNT)]
mod app { /*...*/ }
```
Пример `init` также зависит от крейта `panic-semihosting`:
``` console
$ cargo add panic-semihosting
```
5. Соберите его, загрузите в микроконтроллер и запустите.
``` console
$ # ПРИМЕЧАНИЕ: Я раскомментировал опцию `runner` в `.cargo/config`
$ cargo run
{{#include ../../../../ci/expected/init.run}}
```

149
book/ru/src/by-example/resources.md
View file

@ -1,149 +0,0 @@
# Ресурсы
Фреймворк предоставляет абстракцию для разделения данных между любыми контекстами,
с которыми мы встречались в предыдущей главе (задачами-обработчиками, `init` и `idle`): ресурсы.
Ресурсы - это данные, видимые только функциями, определенными внутри модуля `#[app]`.
Фреймворк дает пользователю полный контроль за тем, какой контекст может
получить доступ к какому ресурсу.
Все ресурсы определены в одной структуре внутри модуля `#[app]`.
Каждое поле структуры соответствует отдельному ресурсу.
`struct`-ура должна быть аннотирована следующим атрибутом: `#[resources]`.
Ресурсам могут быть опционально даны начальные значения с помощью атрибута `#[init]`.
Ресурсы, которым не передано начально значение, называются
*поздними* ресурсами, более детально они описаны в одном из разделов на этой странице.
Каждый контекс (задача-обработчик, `init` или `idle`) должен указать ресурсы, к которым
он намерен обращаться, в соответсятвующем ему атрибуте с метаданными, используя
аргумент `resources`. Этот аргумент принимает список имен ресурсов в качестве значения.
Перечисленные ресурсы становятся доступны в контексте через поле `resources` структуры `Context`.
Пример программы, показанной ниже содержит два обработчика прерывания, которые разделяют
доступ к ресурсу под названием `shared`.
``` rust
{{#include ../../../../examples/resource.rs}}
```
``` console
$ cargo run --example resource
{{#include ../../../../ci/expected/resource.run}}
```
Заметьте, что к ресурсу `shared` нельзя получить доступ из `idle`. Попытка сделать это
приведет к ошибке компиляции.
## `lock`
Критические секции необходимы для разделения изменяемых данных таким образом,
чтобы избежать гонок данных.
Поле `resources`, передаваемого `Context` реализует трейт [`Mutex`] для каждого разделяемого
ресурса, доступного задаче.
Единственный метод этого трейта, [`lock`], запускает свой аргумент-замыкание в критической секции.
[`Mutex`]: ../../../api/rtic/trait.Mutex.html
[`lock`]: ../../../api/rtic/trait.Mutex.html#method.lock
Критическая секция, создаваемая интерфейсом `lock` основана на динамических приоритетах:
она временно повышает динамический приоритет контекста до *максимального* приоритета,
что не дает другим задачам возможности вытеснить критическую секцию.
Этот протокол синхронизации известен как [Протокол немедленного максимального приоритета
(ICPP)][icpp], и компилируется диспетчером RTIC с [Политикой ресурсов стека(SRP)][srp].
[icpp]: https://en.wikipedia.org/wiki/Priority_ceiling_protocol
[srp]: https://en.wikipedia.org/wiki/Stack_Resource_Policy
В примере ниже у нас есть три обработчика прерываний с приоритетами от одного до трех.
Два из обработчиков с более низким приоритетом соревнуются за ресурс `shared`,
поэтому должны блокировать доступа к данным ресурса.
Обработчик с наивысшим приоритетом, который не имеет доступа к ресурсу `shared`,
может свободно вытеснять критическую секцию, созданную обработчиком с низким приоритетом.
``` rust
{{#include ../../../../examples/lock.rs}}
```
``` console
$ cargo run --example lock
{{#include ../../../../ci/expected/lock.run}}
```
## Множественное блокировка
Это расширение к `lock`, чтобы уменьшить количесво отступов, блокируемые ресурсы можно объединять в кортежи.
Следующий пример это демонстрирует:
``` rust
{{#include ../../../../examples/multilock.rs}}
```
## Поздние ресурсы
Поздние ресурсы - такие ресурсы, которым не передано начальное значение во время компиляции
с помощью атрибута `#[init]`, но которые вместо этого инициализируются во время выполнения
с помощью значений из структуры `init::LateResources`, возвращаемой функцией `init`.
Поздние ресурсы полезны, например, для *move* (передача владения) периферии,
инициализированной в `init`, в задачи.
Пример ниже использует поздние ресурсы, чтобы установить неблокируемый односторонний канал
между обработчиком прерывания `UART0` и задачей `idle`. Для канала использована очередь типа
один производитель-один потребитель [`Queue`]. Структура очереди разделяется на потребителя
и производителя в `init`, а затем каждая из частей располагается в отдельном ресурсу;
`UART0` владеет ресурсом производителя, а `idle` владеет ресурсом потребителя.
[`Queue`]: ../../../api/heapless/spsc/struct.Queue.html
``` rust
{{#include ../../../../examples/late.rs}}
```
``` console
$ cargo run --example late
{{#include ../../../../ci/expected/late.run}}
```
## Только разделяемый доступ
По-умолчанию фреймворк предполагает, что все задачи требуют эксклюзивный доступ (`&mut-`) к ресурсам,
но возможно указать, что задаче достаточен разделяемый доступ (`&-`) к ресурсы с помощью синтакисиса
`&resource_name` в списке `resources`.
Преимущество указания разделяемого досупа (`&-`) к ресурсу в том, что для доступа к ресурсу
не нужна блокировка, даже если за ресурс соревнуются несколько задач, запускаемые с
разными приоритетами. Недостаток в том, что задача получает только разделяемую ссылку (`&-`)
на ресурс, и ограничена операциями, возможными с ней, но там, где разделяемой ссылки достаточно,
такой подход уменьшает количесво требуемых блокировок.
В дополнение к простым неизменяемым данным, такой разделяемый доступ может быть полезен для
ресурсов, безопасно реализующих внутреннюю мутабельность с самоблокировкой или атомарными операциями.
Заметьте, что в этом релизе RTIC невозможно запросить и эксклюзивный доступ (`&mut-`)
и разделяемый (`&-`) для *одного и того же* ресурса из различных задач.
Попытка это сделать приведет к ошибке компиляции.
В примере ниже ключ (например криптографический ключ) загружается (или создается) во время выполнения,
а затем используется двумя задачами, запускаемымы с различным приоритетом без каких-либо блокировок.
``` rust
{{#include ../../../../examples/only-shared-access.rs}}
```
``` console
$ cargo run --example only-shared-access
{{#include ../../../../ci/expected/only-shared-access.run}}
```
## Неблокируемый доступ к изменяемым ресурсам
Есть две других возможности доступа к ресурсам
* `#[lock_free]`: могут быть несколько задач с одинаковым приоритетом,
получающие доступ к ресурсу без критических секций. Так как задачи с
одинаковым приоритетом никогда не могут вытеснить друг друга, это безопасно.
* `#[task_local]`: в этом случае должна быть только одна задача, использующая
этот ресурс, так же как локальный `static mut` ресурс задачи, но (опционально) устанавливаемая с в init.

116
book/ru/src/by-example/tasks.md
View file

@ -1,116 +0,0 @@
# Программные задачи
В дополнение к аппаратным задачам, вызываемым в ответ на аппаратные события,
RTIC также поддерживает *программные* задачи, которые могут порождаться
приложением из любого контекста выполнения.
Программным задачам можно также назначать приоритет и, под капотом, они
диспетчеризуются обработчиками прерываний. RTIC требует, чтобы свободные
прерывания, были указаны в аргументе `dispatchers` модуля `app`, если используются
программные задачи; часть из этих свободных прерываний будут использованы для
управления программными задачами. Преимущество программных задач над аппаратными
в том, что множество задач можно назначить на один обработчик прерывания.
Программные задачи также определяются атрибутом `task`, но аргумент `binds` опускается.
Пример ниже демонстрирует три программные задачи, запускаемых 2-х разных приоритетах.
Три программные задачи привязаны к 2-м обработчикам прерываний.
``` rust
{{#include ../../../../examples/task.rs}}
```
``` console
$ cargo run --example task
{{#include ../../../../ci/expected/task.run}}
```
## Передача сообщений
Другое преимущество программной задачи в том, что задачам можно передать сообщения
в момент их запуска. Тип передаваемого сообщения должен быть определен в сигнатуре
задачи-обработчика.
Пример ниже демонстрирует три задачи, две из которых ожидают сообщение.
``` rust
{{#include ../../../../examples/message.rs}}
```
``` console
$ cargo run --example message
{{#include ../../../../ci/expected/message.run}}
```
## Вместимость
RTIC *не* производит никакого рода аллокаций памяти в куче.
Память, необходимая для размещения сообщения резервируется статически.
По-умолчанию фреймворк минимизирует выделение памяти программой таким образом,
что каждая задача имеет "вместимость" для сообщения равную 1:
это значит, что не более одного сообщения можно передать задаче перед тем, как
у нее появится возможность к запуску. Это значение по-умолчанию можно
изменить для каждой задачи, используя аргумент `capacity`.
Этот аргумент принимает положительное целое, которое определяет как много
сообщений буфер сообщений задачи может хранить.
Пример ниже устанавливает вместимость программной задачи `foo` равной 4.
Если вместимость не установить, второй вызов `spawn.foo` в `UART0` приведет к ошибке (панике).
``` rust
{{#include ../../../../examples/capacity.rs}}
```
``` console
$ cargo run --example capacity
{{#include ../../../../ci/expected/capacity.run}}
```
## Обработка ошибок
Интерфейс `spawn` возвращает вариант `Err`, если для размещения сообщения нет места.
В большинстве сценариев возникающие ошибки обрабатываются одним из двух способов:
- Паника, с помощью `unwrap`, `expect`, и т.п. Этот метод используется, чтобы обнаружить
ошибку программиста (например bug) выбора вместительности, которая оказалась недостаточна.
Когда эта паника встречается во время тестирования, выбирается большая вместительность,
и перекомпиляция программы может решить проблему, но иногда достаточно окунуться глубже
и провести анализ времени выполнения программы, чтобы выяснить, может ли платформа
обрабатывать пиковые нагрузки, или процессор необходимо заменить на более быстрый.
- Игнорирование результата. В программах реального времени, как и в обычных, может быть
нормальным иногда терять данные, или не получать ответ на некоторые события в пиковых ситуациях.
В таких сценариях может быть допустимо игнорирование ошибки вызова `spawn`.
Следует отметить, что повторная попытка вызова `spawn` обычно неверный подход, поскольку
такая операция на практике вероятно никогда не завершится успешно.
Так как у нас есть только переключения контекста на задачи с *более высоким* приоритетом,
повторение вызова `spawn` на задаче с низким приоритом никогда не позволит планировщику
вызвать задачу, что значит, что буфер никогда не будет очищен. Такая ситуация отражена в
следующем наброске:
``` rust
#[rtic::app(..)]
mod app {
#[init(spawn = [foo, bar])]
fn init(cx: init::Context) {
cx.spawn.foo().unwrap();
cx.spawn.bar().unwrap();
}
#[task(priority = 2, spawn = [bar])]
fn foo(cx: foo::Context) {
// ..
// программа зависнет здесь
while cx.spawn.bar(payload).is_err() {
// повтор попытки вызова spawn, если произошла ошибка
}
}
#[task(priority = 1)]
fn bar(cx: bar::Context, payload: i32) {
// ..
}
}
```

108
book/ru/src/by-example/timer-queue.md
View file

@ -1,108 +0,0 @@
# Очередь таймера
В отличие от интерфейса `spawn`, который немедленно передает программную задачу
планировщику для немедленного запуска, интерфейс `schedule` можно использовать
для планирования задачи к запуске через какое-то время в будущем.
Чтобы использовать интерфейс `schedule`, предварительно должен быть определен
монотонный таймер с помощью аргумента `monotonic` атрибута `#[app]`.
Этот аргумент принимает путь к типу, реализующему трейт [`Monotonic`].
Ассоциированный тип, `Instant`, этого трейта представляет метку времени в соответствущих
единицах измерения и широко используется в интерфейсе `schedule` -- предлагается смоделировать
этот тип позднее [один из таких есть в стандартной библиотеке][std-instant].
Хотя это не отражено в определении трейта (из-за ограничений системы типов / трейтов),
разница двух `Instant`ов должна возвращать какой-то тип `Duration` (см. [`core::time::Duration`])
и этот `Duration` должен реализовывать трейт `TryInto<u32>`.
Реализация этого трейта должна конвертировать значение `Duration`, которое
использует какую-то определенную единицу измерения времени, в единицы измерения "тактов системного таймера
(SYST)". Результат преобразований должен быть 32-битным целым.
Если результат не соответствует 32-битному целому, тогда операция должна возвращать ошибку любого типа.
[`Monotonic`]: ../../../api/rtic/trait.Monotonic.html
[std-instant]: https://doc.rust-lang.org/std/time/struct.Instant.html
[`core::time::Duration`]: https://doc.rust-lang.org/core/time/struct.Duration.html
Для целевых платформ ARMv7+ крейт `rtic` предоставляет реализацию `Monotonic`, основанную на
встроенном CYCle CouNTer (CYCCNT). Заметьте, что это 32-битный таймер, работающий на
частоте центрального процессора, и поэтому не подходит для отслеживания интервалов времени в секундах.
Когда планируется задача, (определенный пользователем) `Instant`, в который задача должна быть
выполнена, должен передаваться в качестве первого аргумента вызова `schedule`.
К тому же, выбранный `monotonic` таймер, необходимо сконфигурировать и инициализировать в
фазе работы `#[init]`. Заметьте, что *также* касается случая использования `CYCCNT`,
предоставляемого крейтом `cortex-m-rtic`.
Пример ниже планирует к выполнению две задачи из `init`: `foo` и `bar`. `foo` запланирована
к запуску через 8 миллионов циклов в будущем. Далее, `bar` запланировано запустить через
4 миллиона циклов в будущем. Таким образом, `bar` запустится до `foo`, так как и запланировано.
> **DF:YJ**: Примеры, использующие интерфейс `schedule` или абстракцию `Instant`
> **не будут** правильно работать на эмуляторе QEMU, поскольку счетчик циклов Cortex-M
> функционально не был реализован в `qemu-system-arm`.
``` rust
{{#include ../../../../examples/schedule.rs}}
```
Запусе программы на реальном оборудовании создает следующий вывод в консоли:
``` text
{{#include ../../../../ci/expected/schedule.run}}
```
Когда интерфейс `schedule` используется, среда исполнения использует внутри
обработчик прерываний `SysTick` и периферию системного таймера (`SYST`), поэтому ни
тот ни другой нельзя использовать в программе. Это гарантируется изменением типа
`init::Context.core` с `cortex_m::Peripherals` на `rtic::Peripherals`.
Последняя структура содержит все поля из предыдущей кроме `SYST`.
## Периодические задачи
Программные задачи имеют доступ к моменту времени `Instant`, в который они были запланированы
на выполнение переменной `scheduled`. Эта информация и интерфейс `schedule` можно использовать,
чтобы реализовать периодические задачи, как показано ниже.
``` rust
{{#include ../../../../examples/periodic.rs}}
```
Это вывод, создаваемый примером. Заметьте, что здесь пристствует небольшой дрейф / колебания
даже несмотря на то, что `schedule.foo` была вызвана в *конце* `foo`. Использование
`Instant::now` вместо `scheduled` вызвало бы дрейф / колебания.
``` text
{{#include ../../../../ci/expected/periodic.run}}
```
## Базовое время
Для задач, вызываемых из `init` мы имеем точную информацию о их `scheduled` времени.
Для аппаратных задач такого времени нет, поскольку они асинхронны по природе.
Для аппаратных задач среда исполнения предоставляет время запуска (`start`), которое отражает
время, в которое обработчик прерывания будет запущен.
Заметьте, что `start` **не** равно времени прихода события, которое вызывает задачу.
В зависимости от приоритета задачи и загрузки системы, время `start` может сильно отдалиться от
времени прихода события.
Какое по вашему мнению будет значение `scheduled` для программных задач, которые вызываются через
`spawn` вместо планирования? Ответ в том, что вызываемые задачи наследуют
*базовое* время того контекста, который их вызывает. Базовое время аппаратных задач -
это их время `start`, базовое время программных задач - их время `scheduled`, а
базовое время `init` - время старта системы, или нулевое
(`Instant::zero()`). `idle` на самом деле не имеет базового времени, но задачи вызываемые из нее,
используют `Instant::now()` в качестве базового.
Пример ниже демонстрирует разные смыслы *базового времени*.
``` rust
{{#include ../../../../examples/baseline.rs}}
```
Запуск программы на реальном оборудовании приведет к следующему выводу в консоли:
``` text
{{#include ../../../../ci/expected/baseline.run}}
```

171
book/ru/src/by-example/tips.md
View file

@ -1,171 +0,0 @@
# Советы и хитрости
## Обобщенное программирование (Generics)
Все объекты, предоставляющие ресурысы реализуют трейт `rtic::Mutex`.
Если ресурс не реализует его, можно обернуть его в новый тип [`rtic::Exclusive`],
который реализует трейт `Mutex`. С помощью этого нового типа
можно написать обобщенную функцию, которая работает с обобщенным ресурсом и
вызывать его из различных задач, чтобы производить однотипные операции над
похожим множеством ресурсов.
Вот один такой пример:
[`rtic::Exclusive`]: ../../../api/rtic/struct.Exclusive.html
``` rust
{{#include ../../../../examples/generics.rs}}
```
``` console
$ cargo run --example generics
{{#include ../../../../ci/expected/generics.run}}
```
## Условная компиляция
Вы можете использовать условную компиляцию (`#[cfg]`) на ресурсах (полях структуры
`#[resources] struct Resources`) и задачах (элементах `fn`).
Эффект использования атрибутов `#[cfg]` в том, что ресурс/ задача
будут *не* доступны в соответствующих структурах `Context` если условие не выполняется.
В примере ниже выводится сообщение каждый раз, когда вызывается задача `foo`, но только
если программы скомпилирова с профилем `dev`.
``` rust
{{#include ../../../../examples/cfg.rs}}
```
``` console
$ cargo run --example cfg --release
$ cargo run --example cfg
{{#include ../../../../ci/expected/cfg.run}}
```
## Запуск задач из ОЗУ
Главной целью переноса описания программы на RTIC в атрибуты в
RTIC v0.4.x была возможность взаимодействия с другими атрибутами.
Напримерe, атрибут `link_section` можно применять к задачам, чтобы разместить
их в ОЗУ; это может улучшить производительность в некоторых случаях.
> **ВАЖНО**: Обычно атрибуты `link_section`, `export_name` и `no_mangle`
> очень мощные, но их легко использовать неправильно. Неверное использование
> любого из этих атрибутов может вызвать неопределенное поведение;
> Вам следует всегда предпочитать использование безопасных, высокоуровневых
> атрибутов вместо них, таких как атрибуты `interrupt` и `exception`
> из `cortex-m-rt`.
>
> В особых функций, размещаемых в ОЗУ нет безопасной абстракции в `cortex-m-rt`
> v0.6.5 но создано [RFC] для добавления атрибута `ramfunc` в будущем релизе.
[RFC]: https://github.com/rust-embedded/cortex-m-rt/pull/100
В примере ниже показано как разместить высокоприоритетную задачу `bar` в ОЗУ.
``` rust
{{#include ../../../../examples/ramfunc.rs}}
```
Запуск этой программы создаст ожидаемый вывод.
``` console
$ cargo run --example ramfunc
{{#include ../../../../ci/expected/ramfunc.run}}
```
Можно посмотреть на вывод `cargo-nm`, чтобы убедиться, что `bar` расположен в ОЗУ
(`0x2000_0000`), тогда как `foo` расположен во Flash (`0x0000_0000`).
``` console
$ cargo nm --example ramfunc --release | grep ' foo::'
{{#include ../../../../ci/expected/ramfunc.grep.foo}}
```
``` console
$ cargo nm --example ramfunc --release | grep ' bar::'
{{#include ../../../../ci/expected/ramfunc.grep.bar}}
```
## Обходной путь для быстрой передачи сообщений
Передача сообщений всегда вызывает копирование от отправителя в
статическую переменную, а затем из статической переменной получателю.
Таким образом, при передаче большого буфера, например `[u8; 128]`, передача сообщения
вызывает два дорогих вызова `memcpy`. Чтобы минимизировать накладные расходы на передачу
сообщения, можно использовать обходной путь: вместо передачи буфера по значению,
можно передавать владеющий указатель на буфер.
Можно использовать глобальный аллокатор, чтобы реализовать данный трюк (`alloc::Box`,
`alloc::Rc`, и т.п.), либо использовать статически аллоцируемый пул памяти, например [`heapless::Pool`].
[`heapless::Pool`]: https://docs.rs/heapless/0.5.0/heapless/pool/index.html
Здесь приведен пример использования `heapless::Pool` для "упаковки" буфера из 128 байт.
``` rust
{{#include ../../../../examples/pool.rs}}
```
``` console
$ cargo run --example pool
{{#include ../../../../ci/expected/pool.run}}
```
## Инспектирование раскрываемого кода
`#[rtic::app]` - это процедурный макрос, который создает код.
Если по какой-то причине вам нужно увидеть код, сгенерированный этим макросом,
у вас есть два пути:
Вы можете изучить файл `rtic-expansion.rs` внутри папки `target`. Этот файл
содержит элемент `#[rtic::app]` в раскрытом виде (не всю вашу программу!)
из *последней сборки* (с помощью `cargo build` или `cargo check`) RTIC программы.
Раскрытый код не отформатирован по-умолчанию, но вы можете запустить `rustfmt`
на нем перед тем, как читать.
``` console
$ cargo build --example foo
$ rustfmt target/rtic-expansion.rs
$ tail target/rtic-expansion.rs
```
``` rust
#[doc = r" Implementation details"]
mod app {
#[doc = r" Always include the device crate which contains the vector table"]
use lm3s6965 as _;
#[no_mangle]
unsafe extern "C" fn main() -> ! {
rtic::export::interrupt::disable();
let mut core: rtic::export::Peripherals = core::mem::transmute(());
core.SCB.scr.modify(|r| r | 1 << 1);
rtic::export::interrupt::enable();
loop {
rtic::export::wfi()
}
}
}
```
Или, вы можете использовать подкоманду [`cargo-expand`]. Она раскроет
*все* макросы, включая атрибут `#[rtic::app]`, и модули в вашем крейте и
напечатает вывод в консоль.
[`cargo-expand`]: https://crates.io/crates/cargo-expand
``` console
$ # создаст такой же вывод, как выше
$ cargo expand --example smallest | tail
```
## Деструктуризация ресурса
Если задача требует нескольких ресурсов, разбиение структуры ресурсов
может улучшить читабельность. Вот два примера того, как это можно сделать:
``` rust
{{#include ../../../../examples/destructure.rs}}
```

49
book/ru/src/by-example/types-send-sync.md
View file

@ -1,49 +0,0 @@
# Типы, Send и Sync
Каждая функция в модуле `app` принимает структуру `Context` в качесте первого параметра.
Все поля этих структур имеют предсказуемые, неанонимные типы,
поэтому вы можете написать обычные функции, принимающие их как аргументы.
Справочник по API определяет как эти типы генерируются на основе входных данных.
Вы можете также сгенерировать документацию к вашему крейту программы (`cargo doc --bin <name>`);
в документации вы найдете структуры `Context` (например `init::Context` и
`idle::Context`).
Пример ниже показывает различные типы, сгенерированные атрибутом `app`.
``` rust
{{#include ../../../../examples/types.rs}}
```
## `Send`
[`Send`] - это маркерный трейт для "типов, которые можно передавать через границы
потоков", как это определено в `core`. В контексте RTIC трейт `Send` необходим
только там, где возможна передача значения между задачами, запускаемыми на
*разных* приоритетах. Это возникает в нескольких случаях: при передаче сообщений,
в разделяемых `static mut` ресурсах и при инициализации поздних ресурсов.
[`Send`]: https://doc.rust-lang.org/core/marker/trait.Send.html
Атрибут `app` проверит, что `Send` реализован, где необходимо, поэтому вам не
стоит волноваться об этом. В настоящий момент все передаваемые типы в RTIC должны быть `Send`, но
это ограничение возможно будет ослаблено в будущем.
## `Sync`
Аналогично, [`Sync`] - маркерный трейт для "типов, на которые можно безопасно разделять между потоками",
как это определено в `core`. В контексте RTIC типаж `Sync` необходим только там,
где возможно для двух или более задач, запускаемых на разных приоритетах получить разделяемую ссылку (`&-`) на
ресурс. Это возникает только (`&-`) ресурсах с разделяемым доступом.
[`Sync`]: https://doc.rust-lang.org/core/marker/trait.Sync.html
Атрибут `app` проверит, что `Sync` реализован, где необходимо, но важно знать,
где ограничение `Sync` не требуется: в (`&-`) ресурсах с разделяемым доступом, за которые
соперничают задачи с *одинаковым* приоритетом.
В примере ниже показано, где можно использовать типы, не реализующие `Sync`.
``` rust
{{#include ../../../../examples/not-sync.rs}}
```

14
book/ru/src/internals.md
View file

@ -1,14 +0,0 @@
# Под капотом
**Этот раздел в настоящий момент находится в разработке,
он появится снова, когда будет завершен**
Этот раздел описывает внутренности фреймворка RTIC на *высоком уровне*.
Низкоуровневые детали, такие как парсинг и генерация кода, выполняемые процедурным макросом
(`#[app]`) объясняться не будут. Внимание будет сосредоточено на анализе
спецификации пользователя и структурах данных, используемых на этапе выполнения.
Мы настоятельно рекомендуем вам прочитать раздел о [конкуренции] в embedonomicon
перед тем, как погружаться в материал.
[конкуренции]: https://github.com/rust-embedded/embedonomicon/pull/48

158
book/ru/src/internals/access.md
View file

@ -1,158 +0,0 @@
# Контроль доступа
Одна из основ RTIC - контроль доступа. Контроль того, какая часть программы
может получить доступ к какой статической переменной - инструмент обеспечения
безопасности памяти.
Статические переменные используются для разделения состояний между обработчиками
прерываний, или между обработчиком прерывания и нижним контекстом выполнения, `main`.
В обычном Rust коде трудно обеспечить гранулированный контроль за тем, какие функции
могут получать доступ к статическим переменным, поскольку к статическим переменным
можно получить доступ из любой функции, находящейся в той же области видимости,
в которой они определены. Модули дают частичный контроль над доступом
к статическим переменным, но они недостаточно гибкие.
Чтобы добиться полного контроля за тем, что задачи могут получить доступ
только к статическим переменным (ресурсам), которые им были указаны в RTIC атрибуте,
фреймворк RTIC производит трансформацию структуры кода.
Эта трансформация состоит из размещения ресурсов (статических переменных), определенных
пользователем *внутри* модуля, а пользовательского кода *вне* модуля.
Это делает невозможным обращение пользовательского кода к статическим переменным.
Затем доступ к ресурсам предоставляется каждой задаче с помощью структуры `Resources`,
чьи поля соответствуют ресурсам, к которым получает доступ задача.
Есть лишь одна такая структура на задачу и структура `Resources` инициализируется
либо уникальной ссылкой (`&mut-`) на статическую переменную, либо с помощью прокси-ресурса (см.
раздел [критические секции](critical-sections.html)).
Код ниже - пример разных трансформаций структуры кода, происходящих за сценой:
``` rust
#[rtic::app(device = ..)]
mod app {
static mut X: u64: 0;
static mut Y: bool: 0;
#[init(resources = [Y])]
fn init(c: init::Context) {
// .. пользовательский код ..
}
#[interrupt(binds = UART0, resources = [X])]
fn foo(c: foo::Context) {
// .. пользовательский код ..
}
#[interrupt(binds = UART1, resources = [X, Y])]
fn bar(c: bar::Context) {
// .. пользовательский код ..
}
// ..
}
```
Фреймворк создает код, подобный этому:
``` rust
fn init(c: init::Context) {
// .. пользовательский код ..
}
fn foo(c: foo::Context) {
// .. пользовательский код ..
}
fn bar(c: bar::Context) {
// .. пользовательский код ..
}
// Публичное API
pub mod init {
pub struct Context<'a> {
pub resources: Resources<'a>,
// ..
}
pub struct Resources<'a> {
pub Y: &'a mut bool,
}
}
pub mod foo {
pub struct Context<'a> {
pub resources: Resources<'a>,
// ..
}
pub struct Resources<'a> {
pub X: &'a mut u64,
}
}
pub mod bar {
pub struct Context<'a> {
pub resources: Resources<'a>,
// ..
}
pub struct Resources<'a> {
pub X: &'a mut u64,
pub Y: &'a mut bool,
}
}
/// Детали реализации
mod app {
// все, что внутри этого модуля спрятано от пользовательского кода
static mut X: u64 = 0;
static mut Y: bool = 0;
// настоящая точка входа в программу
unsafe fn main() -> ! {
interrupt::disable();
// ..
// вызов пользовательского кода; передача ссылок на статические переменные
init(init::Context {
resources: init::Resources {
X: &mut X,
},
// ..
});
// ..
interrupt::enable();
// ..
}
// обработчик прерывания,с которым связан `foo`
#[no_mangle]
unsafe fn UART0() {
// вызов пользовательского кода; передача ссылок на статические переменные
foo(foo::Context {
resources: foo::Resources {
X: &mut X,
},
// ..
});
}
// обработчик прерывания,с которым связан `bar`
#[no_mangle]
unsafe fn UART1() {
// вызов пользовательского кода; передача ссылок на статические переменные
bar(bar::Context {
resources: bar::Resources {
X: &mut X,
Y: &mut Y,
},
// ..
});
}
}
```

92
book/ru/src/internals/ceilings.md
View file

@ -1,92 +0,0 @@
# Анализ приоритетов
*Поиск максимального приоритета* ресурса (*ceiling*) - поиск динамического
приоритета, который любая задача должна иметь, чтобы безопасно работать с
памятью ресурсов. Анализ приоритетов - относительно прост,
но критичен для безопасности памяти RTIC программ.
Для расчета максимального приоритета ресурса мы должны сначала составить
список задач, имеющих доступ к ресурсу -- так как фреймворк RTIC
форсирует контроль доступа к ресурсам на этапе компиляции, он
также имеет доступ к этой информации на этапе компиляции.
Максимальный приоритет ресурса - просто наивысший логический приоритет
среди этих задач.
`init` и `idle` не настоящие задачи, но у них есть доступ к ресурсам,
поэтому они должны учитываться при анализе приоритетов.
`idle` учитывается как задача, имеющая логический приоритет `0`,
в то время как `init` полностью исключается из анализа --
причина этому в том, что `init` никогда не использует (не нуждается) критические
секции для доступа к статическим переменным.
В предыдущем разделе мы показывали, что разделяемые ресусы
могут быть представлены уникальными ссылками (`&mut-`) или скрываться за
прокси в зависимости от того, имеет ли задача к ним доступ.
Какой из вариантов представляется задаче зависит от приоритета задачи и
максимального приоритета ресурса.
Если приоритет задачи такой же, как максимальный приоритет ресурса, тогда
задача получает уникальную ссылку (`&mut-`) на память ресурса,
в противном случае задача получает прокси -- это также касается `idle`.
`init` особеннвй: он всегда получает уникальные ссылки (`&mut-`) на ресурсы.
Пример для иллюстрации анализа приоритетов:
``` rust
#[rtic::app(device = ..)]
mod app {
struct Resources {
// доступен из `foo` (prio = 1) и `bar` (prio = 2)
// -> CEILING = 2
#[init(0)]
x: u64,
// доступен из `idle` (prio = 0)
// -> CEILING = 0
#[init(0)]
y: u64,
}
#[init(resources = [x])]
fn init(c: init::Context) {
// уникальная ссылка, потому что это `init`
let x: &mut u64 = c.resources.x;
// уникальная ссылка, потому что это `init`
let y: &mut u64 = c.resources.y;
// ..
}
// PRIORITY = 0
#[idle(resources = [y])]
fn idle(c: idle::Context) -> ! {
// уникальная ссылка, потому что
// приоритет (0) == максимальному приоритету ресурса (0)
let y: &'static mut u64 = c.resources.y;
loop {
// ..
}
}
#[interrupt(binds = UART0, priority = 1, resources = [x])]
fn foo(c: foo::Context) {
// прокси-ресурс, потому что
// приоритет задач (1) < максимальному приоритету ресурса (2)
let x: resources::x = c.resources.x;
// ..
}
#[interrupt(binds = UART1, priority = 2, resources = [x])]
fn bar(c: foo::Context) {
// уникальная ссылка, потому что
// приоритет задачи (2) == максимальному приоритету ресурса (2)
let x: &mut u64 = c.resources.x;
// ..
}
// ..
}
```

521
book/ru/src/internals/critical-sections.md
View file

@ -1,521 +0,0 @@
# Критические секции
Когда ресурсы (статические переменные) разделяются между двумя или более задачами,
которые выполняются с разными приоритетами, некая форма запрета изменений
необходима, чтобы изменять память без гонки данных. В RTIC мы используем
основанные на приоритетах критические секции, чтобы гарантировать запрет изменений
(см. [Протокол немедленного максимального приоритета][icpp]).
[icpp]: https://en.wikipedia.org/wiki/Priority_ceiling_protocol
Критическия секция состоит во временном увеличении *динамического* приоритета задачи.
Пока задача находится в критической секции, все другие задачи, которые могут
послать запрос переменной *не могут запуститься*.
Насколько большим должен быть динамический приориткт, чтобы гарантировать запрет изменений
определенного ресурса? [Анализ приоритетов](ceilings.html) отвечает на этот вопрос
и будет обсужден в следующем разделе. В этом разделе мы сфокусируемся
на реализации критической секции.
## Прокси-ресурсы
Для упрощения, давайте взглянем на ресурс, разделяемый двумя задачами,
запускаемыми с разными приоритетами. Очевидно, что одна задача может вытеснить
другую; чтобы предотвратить гонку данных задача с *низким приоритетом* должна
использовать критическую секцию, когда необходимо изменять разделяемую память.
С другой стороны, высокоприоритетная задача может напрямую изменять
разделяемую память, поскольку не может быть вытеснена низкоприоритетной задачей.
Чтобы заставить использовать критическую секцию на задаче с низким приоритетом,
мы предоставляем *прокси-ресурсы*, в которых мы отдаем уникальную ссылку
(`&mut-`) высокоприоритетной задаче.
Пример ниже показывает разные типы, передаваемые каждой задаче:
``` rust
#[rtic::app(device = ..)]
mut app {
struct Resources {
#[init(0)]
x: u64,
}
#[interrupt(binds = UART0, priority = 1, resources = [x])]
fn foo(c: foo::Context) {
// прокси-ресурс
let mut x: resources::x = c.resources.x;
x.lock(|x: &mut u64| {
// критическая секция
*x += 1
});
}
#[interrupt(binds = UART1, priority = 2, resources = [x])]
fn bar(c: bar::Context) {
let mut x: &mut u64 = c.resources.x;
*x += 1;
}
// ..
}
```
Теперь давайте посмотрим. как эти типы создаются фреймворком.
``` rust
fn foo(c: foo::Context) {
// .. пользовательский код ..
}
fn bar(c: bar::Context) {
// .. пользовательский код ..
}
pub mod resources {
pub struct x {
// ..
}
}
pub mod foo {
pub struct Resources {
pub x: resources::x,
}
pub struct Context {
pub resources: Resources,
// ..
}
}
pub mod bar {
pub struct Resources<'a> {
pub x: &'a mut u64,
}
pub struct Context {
pub resources: Resources,
// ..
}
}
mod app {
static mut x: u64 = 0;
impl rtic::Mutex for resources::x {
type T = u64;
fn lock<R>(&mut self, f: impl FnOnce(&mut u64) -> R) -> R {
// мы рассмотрим это детально позднее
}
}
#[no_mangle]
unsafe fn UART0() {
foo(foo::Context {
resources: foo::Resources {
x: resources::x::new(/* .. */),
},
// ..
})
}
#[no_mangle]
unsafe fn UART1() {
bar(bar::Context {
resources: bar::Resources {
x: &mut x,
},
// ..
})
}
}
```
## `lock`
Теперь давайте рассмотрим непосредственно критическую секцию. В этом примере мы должны
увеличить динамический приоритет минимум до `2`, чтобы избежать гонки данных.
В архитектуре Cortex-M динамический приоритет можно изменить записью в регистр `BASEPRI`.
Семантика регистра `BASEPRI` такова:
- Запись `0` в `BASEPRI` отключает его функциональность.
- Запись ненулевого значения в `BASEPRI` изменяет уровень приоритета, требуемого для
вытеснения прерывания. Однако, это имеет эффект, только когда записываемое значение
*меньше*, чем уровень приоритета текущего контекста выполнения, но обращаем внимание, что
более низкий уровень аппаратного приоритета означает более высокий логический приоритет
Таким образом, динамический приоритет в любой момент времени может быть рассчитан как
``` rust
dynamic_priority = max(hw2logical(BASEPRI), hw2logical(static_priority))
```
Где `static_priority` - приоритет, запрограммированный в NVIC для текущего прерывания,
или логический `0`, когда текущий контекств - это `idle`.
В этом конкретном примере мы можем реализовать критическую секцию так:
> **ПРИМЕЧАНИЕ:** это упрощенная реализация
``` rust
impl rtic::Mutex for resources::x {
type T = u64;
fn lock<R, F>(&mut self, f: F) -> R
where
F: FnOnce(&mut u64) -> R,
{
unsafe {
// начать критическую секцию: увеличить динамический приоритет до `2`
asm!("msr BASEPRI, 192" : : : "memory" : "volatile");
// запустить пользовательский код в критической секции
let r = f(&mut x);
// окончить критическую секцию: восстановить динамический приоритет до статического значения (`1`)
asm!("msr BASEPRI, 0" : : : "memory" : "volatile");
r
}
}
}
```
В данном случае важно указать `"memory"` в блоке `asm!`.
Это не даст компилятору менять местами операции вокруг него.
Это важно, поскольку доступ к переменной `x` вне критической секции привело бы
к гонке данных.
Важно отметить, что сигнатура метода `lock` препятствет его вложенным вызовам.
Это необходимо для безопасности памяти, так как вложенные вызовы привели бы
к созданию множественных уникальных ссылок (`&mut-`) на `x`, ломая правила заимствования Rust.
Смотреть ниже:
``` rust
#[interrupt(binds = UART0, priority = 1, resources = [x])]
fn foo(c: foo::Context) {
// resource proxy
let mut res: resources::x = c.resources.x;
res.lock(|x: &mut u64| {
res.lock(|alias: &mut u64| {
//~^ ошибка: `res` уже был заимствован уникально (`&mut-`)
// ..
});
});
}
```
## Вложенность
Вложенные вызовы `lock` на *том же* ресурсе должны отклоняться компилятором
для безопасности памяти, однако вложенные вызовы `lock` на *разных* ресурсах -
нормальная операция. В этом случае мы хотим убедиться, что вложенные критические секции
никогда не приведут к понижению динамического приоритета, так как это плохо,
и мы хотим оптимизировать несколько записей в регистр `BASEPRI` и compiler fences.
Чтобы справиться с этим, мы проследим динамический приоритет задачи, с помощью стековой
переменной и используем ее, чтобы решить, записывать `BASEPRI` или нет.
На практике, стековая переменная будет соптимизирована компилятором, но все еще
будет предоставлять информацию компилятору.
Рассмотрим такую программу:
``` rust
#[rtic::app(device = ..)]
mod app {
struct Resources {
#[init(0)]
x: u64,
#[init(0)]
y: u64,
}
#[init]
fn init() {
rtic::pend(Interrupt::UART0);
}
#[interrupt(binds = UART0, priority = 1, resources = [x, y])]
fn foo(c: foo::Context) {
let mut x = c.resources.x;
let mut y = c.resources.y;
y.lock(|y| {
*y += 1;
*x.lock(|x| {
x += 1;
});
*y += 1;
});
// середина
x.lock(|x| {
*x += 1;
y.lock(|y| {
*y += 1;
});
*x += 1;
})
}
#[interrupt(binds = UART1, priority = 2, resources = [x])]
fn bar(c: foo::Context) {
// ..
}
#[interrupt(binds = UART2, priority = 3, resources = [y])]
fn baz(c: foo::Context) {
// ..
}
// ..
}
```
Код, сгенерированный фреймворком, выглядит так:
``` rust
// опущено: пользовательский код
pub mod resources {
pub struct x<'a> {
priority: &'a Cell<u8>,
}
impl<'a> x<'a> {
pub unsafe fn new(priority: &'a Cell<u8>) -> Self {
x { priority }
}
pub unsafe fn priority(&self) -> &Cell<u8> {
self.priority
}
}
// repeat for `y`
}
pub mod foo {
pub struct Context {
pub resources: Resources,
// ..
}
pub struct Resources<'a> {
pub x: resources::x<'a>,
pub y: resources::y<'a>,
}
}
mod app {
use cortex_m::register::basepri;
#[no_mangle]
unsafe fn UART1() {
// статический приоритет прерывания (определено пользователем)
const PRIORITY: u8 = 2;
// сделать снимок BASEPRI
let initial = basepri::read();
let priority = Cell::new(PRIORITY);
bar(bar::Context {
resources: bar::Resources::new(&priority),
// ..
});
// вернуть BASEPRI значение из снимка, сделанного ранее
basepri::write(initial); // то же, что и `asm!` блок, виденный ранее
}
// так же для `UART0` / `foo` и `UART2` / `baz`
impl<'a> rtic::Mutex for resources::x<'a> {
type T = u64;
fn lock<R>(&mut self, f: impl FnOnce(&mut u64) -> R) -> R {
unsafe {
// определение максимального приоритет ресурса
const CEILING: u8 = 2;
let current = self.priority().get();
if current < CEILING {
// увеличить динамический приоритет
self.priority().set(CEILING);
basepri::write(logical2hw(CEILING));
let r = f(&mut y);
// восстановить динамический приоритет
basepri::write(logical2hw(current));
self.priority().set(current);
r
} else {
// динамический приоритет достаточно высок
f(&mut y)
}
}
}
}
// повторить для ресурса `y`
}
```
Наконец, компилятор оптимизирует функцию `foo` во что-то наподобие такого:
``` rust
fn foo(c: foo::Context) {
// ПРИМЕЧАНИЕ: BASEPRI содержит значение `0` (значение сброса) в этот момент
// увеличить динамический приоритет до `3`
unsafe { basepri::write(160) }
// две операции над `y` объединены в одну
y += 2;
// BASEPRI не изменяется для доступа к `x`, потому что динамический приоритет достаточно высок
x += 1;
// уменьшить (восстановить) динамический приоритет до `1`
unsafe { basepri::write(224) }
// средина
// увеличить динамический приоритет до `2`
unsafe { basepri::write(192) }
x += 1;
// увеличить динамический приоритет до `3`
unsafe { basepri::write(160) }
y += 1;
// уменьшить (восстановить) динамический приоритет до `2`
unsafe { basepri::write(192) }
// ПРИМЕЧАНИЕ: было вы правильно объединить эту операцию над `x` с предыдущей, но
// compiler fences грубые и предотвращают оптимизацию
x += 1;
// уменьшить (восстановить) динамический приоритет до `1`
unsafe { basepri::write(224) }
// ПРИМЕЧАНИЕ: BASEPRI содержит значение `224` в этот момент
// обработчик UART0 восстановит значение `0` перед завершением
}
```
## Инвариант BASEPRI
Инвариант, который фреймворк RTIC должен сохранять в том, что значение
BASEPRI в начале обработчика *прерывания* должно быть таким же, как и при выходе
из него. BASEPRI может изменяться в процессе выполнения обработчика прерывания,
но но выполнения обработчика прерывания в начале и конце не должно вызвать
наблюдаемого изменения BASEPRI.
Этот инвариант нужен, чтобы избежать уеличения динамического приоритета до значений,
при которых обработчик не сможет быть вытеснен. Лучше всего это видно на следующем примере:
``` rust
#[rtic::app(device = ..)]
mod app {
struct Resources {
#[init(0)]
x: u64,
}
#[init]
fn init() {
// `foo` запустится сразу после завершения `init`
rtic::pend(Interrupt::UART0);
}
#[task(binds = UART0, priority = 1)]
fn foo() {
// BASEPRI равен `0` в этот момент; динамический приоритет равен `1`
// `bar` вытеснит `foo` в этот момент
rtic::pend(Interrupt::UART1);
// BASEPRI равен `192` в этот момент (из-за бага); динамический приоритет равен `2`
// эта функция возвращается в `idle`
}
#[task(binds = UART1, priority = 2, resources = [x])]
fn bar() {
// BASEPRI равен `0` (динамический приоритет = 2)
x.lock(|x| {
// BASEPRI увеличен до `160` (динамический приоритет = 3)
// ..
});
// BASEPRI восстановлен до `192` (динамический приоритет = 2)
}
#[idle]
fn idle() -> ! {
// BASEPRI равен `192` (из-за бага); динамический приоритет = 2
// это не оказывает эффекта, из-за значени BASEPRI
// задача `foo` не будет выполнена снова никогда
rtic::pend(Interrupt::UART0);
loop {
// ..
}
}
#[task(binds = UART2, priority = 3, resources = [x])]
fn baz() {
// ..
}
}
```
ВАЖНО: давайте например мы *забудем* восстановить `BASEPRI` в `UART1` -- из-за
какого нибудь бага в генераторе кода RTIC.
``` rust
// код, сгенерированный RTIC
mod app {
// ..
#[no_mangle]
unsafe fn UART1() {
// статический приоритет этого прерывания (определен пользователем)
const PRIORITY: u8 = 2;
// сделать снимок BASEPRI
let initial = basepri::read();
let priority = Cell::new(PRIORITY);
bar(bar::Context {
resources: bar::Resources::new(&priority),
// ..
});
// БАГ: ЗАБЫЛИ восстановить BASEPRI на значение из снимка
basepri::write(initial);
}
}
```
В результате, `idle` запустится на динамическом приоритете `2` и на самом деле
система больше никогда не перейдет на динамический приоритет ниже `2`.
Это не компромис для безопасности памяти программы, а влияет на диспетчеризацию задач:
в этом конкретном случае задачи с приоритетом `1` никогда не получат шанс на запуск.

72
book/ru/src/internals/interrupt-configuration.md
View file

@ -1,72 +0,0 @@
# Настройка прерываний
Прерывания - это основа работы программ на RTIC. Правильно настроить приоритеты
прерываний и убедиться, что они не изменяются во время выполнения обязательно
для безопасной работы программы.
Фреймворк RTIC представляет приоритеты прерываний, как нечто, что должно быть определено
на этапе компиляции. Однако, статическая настройка должна быть зашита в соответствующие регистры
в процессе инициализации программы. Настройка прерываний происходит до запуска функции `init`.
Этот пример дает представление о коде, запускаемом фреймворком RTIC:
``` rust
#[rtic::app(device = lm3s6965)]
mod app {
#[init]
fn init(c: init::Context) {
// .. пользовательский код ..
}
#[idle]
fn idle(c: idle::Context) -> ! {
// .. пользовательский код ..
}
#[interrupt(binds = UART0, priority = 2)]
fn foo(c: foo::Context) {
// .. пользовательский код ..
}
}
```
Фреймворк генерирует точку входа в программу, которая выглядит примерно так:
``` rust
// настоящая точку входа в программу
#[no_mangle]
unsafe fn main() -> ! {
// преобразует логические приоритеты в аппаратные / NVIC приоритеты
fn logical2hw(priority: u8) -> u8 {
use lm3s6965::NVIC_PRIO_BITS;
// NVIC кодирует приоритеты верхними битами
// большие значения обозначают меньший приоритет
((1 << NVIC_PRIORITY_BITS) - priority) << (8 - NVIC_PRIO_BITS)
}
cortex_m::interrupt::disable();
let mut core = cortex_m::Peripheral::steal();
core.NVIC.enable(Interrupt::UART0);
// значение, определенное пользователем
let uart0_prio = 2;
// проверка на этапе компиляции, что определенный приоритет входит в поддерживаемый диапазон
let _ = [(); (1 << NVIC_PRIORITY_BITS) - (uart0_prio as usize)];
core.NVIC.set_priority(Interrupt::UART0, logical2hw(uart0_prio));
// вызов пользовательского кода
init(/* .. */);
// ..
cortex_m::interrupt::enable();
// вызов пользовательского кода
idle(/* .. */)
}
```

114
book/ru/src/internals/late-resources.md
View file

@ -1,114 +0,0 @@
# Поздние ресурсы
Некоторые ресурсы инициализируются во время выполнения после завершения функции `init`.
Важно то, что ресурсы (статические переменные) полностью инициализируются
до того, как задачи смогут запуститься, вот почему они должны быть инициализированы
пока прерывания отключены.
Ниже показан пример кода, генерируемого фреймворком для инициализации позних ресурсов.
``` rust
#[rtic::app(device = ..)]
mod app {
struct Resources {
x: Thing,
}
#[init]
fn init() -> init::LateResources {
// ..
init::LateResources {
x: Thing::new(..),
}
}
#[task(binds = UART0, resources = [x])]
fn foo(c: foo::Context) {
let x: &mut Thing = c.resources.x;
x.frob();
// ..
}
// ..
}
```
Код, генерируемы фреймворком выглядит примерно так:
``` rust
fn init(c: init::Context) -> init::LateResources {
// .. пользовательский код ..
}
fn foo(c: foo::Context) {
// .. пользовательский код ..
}
// Public API
pub mod init {
pub struct LateResources {
pub x: Thing,
}
// ..
}
pub mod foo {
pub struct Resources<'a> {
pub x: &'a mut Thing,
}
pub struct Context<'a> {
pub resources: Resources<'a>,
// ..
}
}
/// Детали реализации
mod app {
// неинициализированная статическая переменная
static mut x: MaybeUninit<Thing> = MaybeUninit::uninit();
#[no_mangle]
unsafe fn main() -> ! {
cortex_m::interrupt::disable();
// ..
let late = init(..);
// инициализация поздних ресурсов
x.as_mut_ptr().write(late.x);
cortex_m::interrupt::enable(); //~ compiler fence
// исключения, прерывания и задачи могут вытеснить `main` в этой точке
idle(..)
}
#[no_mangle]
unsafe fn UART0() {
foo(foo::Context {
resources: foo::Resources {
// `x` уже инициализирована к этому моменту
x: &mut *x.as_mut_ptr(),
},
// ..
})
}
}
```
Важная деталь здесь то, что `interrupt::enable` ведет себя как like a *compiler
fence*, которое не дает компилятору пореставить запись в `X` *после*
`interrupt::enable`. Если бы компилятор мог делать такие перестановки появились
бы гонки данных между этой записью и любой операцией `foo`, взаимодействующей с `X`.
Архитектурам с более сложным конвейером инструкций нужен барьер памяти
(`atomic::fence`) вместо compiler fence для полной очистки операции записи
перед включением прерываний. Архитектура ARM Cortex-M не нуждается в барьере памяти
в одноядерном контексте.

79
book/ru/src/internals/non-reentrancy.md
View file

@ -1,79 +0,0 @@
# Нереентерабельность
В RTIC задачи-обработчики *не* могут использоваться повторно. Переиспользование задачи-обработчика
может сломать правила заимствования Rust и привести к *неопределенному поведению*.
Задача-обработчик теоретически может быть переиспользована одним из двух способов: программно или аппаратно.
## Программно
Чтобы переиспользовать задачу-обработчик программно, назначенный ей обработчик прерывания
должен быть вызван с помощью FFI (смотрите пример ниже). FFI требует `unsafe` код,
что уменьшает желание конечных пользователей вызывать обработчик прерывания.
``` rust
#[rtic::app(device = ..)]
mod app {
#[init]
fn init(c: init::Context) { .. }
#[interrupt(binds = UART0)]
fn foo(c: foo::Context) {
static mut X: u64 = 0;
let x: &mut u64 = X;
// ..
//~ `bar` может вытеснить `foo` в этом месте
// ..
}
#[interrupt(binds = UART1, priority = 2)]
fn bar(c: foo::Context) {
extern "C" {
fn UART0();
}
// этот обработчик прерывания вызовет задачу-обработчик `foo`, что сломает
// ссылку на статическую переменную `X`
unsafe { UART0() }
}
}
```
Фреймворк RTIC должен сгенерировать код обработчика прерывания, который вызывает
определенные пользователем задачи-обработчики. Мы аккуратны в том, чтобы обеспечить
невозможность вызова этих обработчиков из пользовательского кода.
Пример выше раскрывается в:
``` rust
fn foo(c: foo::Context) {
// .. пользовательский код ..
}
fn bar(c: bar::Context) {
// .. пользовательский код ..
}
mod app {
// все в этом блоке невидимо для пользовательского кода
#[no_mangle]
unsafe fn USART0() {
foo(..);
}
#[no_mangle]
unsafe fn USART1() {
bar(..);
}
}
```
## Аппаратно
Обработчик прерывания также может быть вызван без программного вмешательства.
Это может произойти, если один обработчик будет назначен двум или более прерываниям
в векторе прерываний, но синтаксиса для такого рода функциональности в RTIC нет.

399
book/ru/src/internals/tasks.md
View file

@ -1,399 +0,0 @@
# Программные задачи
RTIC поддерживает программные и аппаратные задачи. Каждая аппаратная задача
назначается на отдельный обработчик прерывания. С другой стороны, несколько
программных задач могут управляться одним обработчиком прерывания --
это сделано, чтобы минимизировать количество обработчиков прерывания,
используемых фреймворком.
Фреймворк группирует задачи, для которых вызывается `spawn` по уровню приоритета,
и генерирует один *диспетчер задачи* для каждого уровня приоритета.
Каждый диспетчер запускается на отдельном обработчике прерывания,
а приоритет этого обработчика прерывания устанавливается так, чтобы соответствовать
уровню приоритета задач, управляемых диспетчером.
Каждый диспетчер задач хранит *очередь* задач, *готовых* к выполнению;
эта очередь называется *очередью готовности*. Вызов программной задачи состоит
из добавления записи в очередь и вызова прерывания, который запускает соответствующий
диспетчер задач. Каждая запись в эту очередь содержит метку (`enum`),
которая идентифицирует задачу, которую необходимо выполнить и *указатель*
на сообщение, передаваемое задаче.
Очередь готовности - неблокируемая очередь типа SPSC (один производитель - один потребитель).
Диспетчер задач владеет конечным потребителем в очереди; конечным производителем
считается ресурс, за который соперничают задачи, которые могут вызывать (`spawn`) другие задачи.
## Дисметчер задач
Давайте сначала глянем на код, генерируемый фреймворком для диспетчеризации задач.
Рассмотрим пример:
``` rust
#[rtic::app(device = ..)]
mod app {
// ..
#[interrupt(binds = UART0, priority = 2, spawn = [bar, baz])]
fn foo(c: foo::Context) {
foo.spawn.bar().ok();
foo.spawn.baz(42).ok();
}
#[task(capacity = 2, priority = 1)]
fn bar(c: bar::Context) {
// ..
}
#[task(capacity = 2, priority = 1, resources = [X])]
fn baz(c: baz::Context, input: i32) {
// ..
}
extern "C" {
fn UART1();
}
}
```
Фреймворк создает следующий диспетчер задач, состоящий из обработчика прерывания и очереди готовности:
``` rust
fn bar(c: bar::Context) {
// .. пользовательский код ..
}
mod app {
use heapless::spsc::Queue;
use cortex_m::register::basepri;
struct Ready<T> {
task: T,
// ..
}
/// вызываемые (`spawn`) задачи, выполняющиеся с уровнем приоритета `1`
enum T1 {
bar,
baz,
}
// очередь готовности диспетчера задач
// `U4` - целое число, представляющее собой емкость этой очереди
static mut RQ1: Queue<Ready<T1>, U4> = Queue::new();
// обработчик прерывания, выбранный для диспетчеризации задач с приоритетом `1`
#[no_mangle]
unsafe UART1() {
// приоритет данного обработчика прерывания
const PRIORITY: u8 = 1;
let snapshot = basepri::read();
while let Some(ready) = RQ1.split().1.dequeue() {
match ready.task {
T1::bar => {
// **ПРИМЕЧАНИЕ** упрощенная реализация
// используется для отслеживания динамического приоритета
let priority = Cell::new(PRIORITY);
// вызов пользовательского кода
bar(bar::Context::new(&priority));
}
T1::baz => {
// рассмотрим `baz` позднее
}
}
}
// инвариант BASEPRI
basepri::write(snapshot);
}
}
```
## Вызов задачи
Интерфейс `spawn` предоставлен пользователю как методы структурв `Spawn`.
Для каждой задачи существует своя структура `Spawn`.
Код `Spawn`, генерируемый фреймворком для предыдущего примера выглядит так:
``` rust
mod foo {
// ..
pub struct Context<'a> {
pub spawn: Spawn<'a>,
// ..
}
pub struct Spawn<'a> {
// отслеживает динамический приоритет задачи
priority: &'a Cell<u8>,
}
impl<'a> Spawn<'a> {
// `unsafe` и спрятано, поскольку сы не хотит, чтобы пользователь вмешивался сюда
#[doc(hidden)]
pub unsafe fn priority(&self) -> &Cell<u8> {
self.priority
}
}
}
mod app {
// ..
// Поиск максимального приоритета для конечного производителя `RQ1`
const RQ1_CEILING: u8 = 2;
// используется, чтобы отследить сколько еще сообщений для `bar` можно поставить в очередь
// `U2` - емкость задачи `bar`; максимум 2 экземпляра можно добавить в очередь
// эта очередь заполняется фреймворком до того, как запустится `init`
static mut bar_FQ: Queue<(), U2> = Queue::new();
// Поиск максимального приоритета для конечного потребителя `bar_FQ`
const bar_FQ_CEILING: u8 = 2;
// приоритет-ориентированная критическая секция
//
// это запускае переданное замыкание `f` с динамическим приоритетом не ниже
// `ceiling`
fn lock(priority: &Cell<u8>, ceiling: u8, f: impl FnOnce()) {
// ..
}
impl<'a> foo::Spawn<'a> {
/// Вызывает задачу `bar`
pub fn bar(&self) -> Result<(), ()> {
unsafe {
match lock(self.priority(), bar_FQ_CEILING, || {
bar_FQ.split().1.dequeue()
}) {
Some(()) => {
lock(self.priority(), RQ1_CEILING, || {
// помещаем задачу в очередь готовности
RQ1.split().1.enqueue_unchecked(Ready {
task: T1::bar,
// ..
})
});
// вызываем прерывание, которое запускает диспетчер задач
rtic::pend(Interrupt::UART0);
}
None => {
// достигнута максимальная вместительность; неудачный вызов
Err(())
}
}
}
}
}
}
```
Использование `bar_FQ` для ограничения числа задач `bar`, которые могут бы вызваны,
может показаться искусственным, но это будет иметь больше смысла, когда мы поговорим
о вместительности задач.
## Сообщения
Мы пропустили, как на самом деле работает передача сообщений, поэтому давайте вернемся
к реализации `spawn`, но в этот раз для задачи `baz`, которая принимает сообщение типа `u64`.
``` rust
fn baz(c: baz::Context, input: u64) {
// .. пользовательский код ..
}
mod app {
// ..
// Теперь мы покажем все содержимое структуры `Ready`
struct Ready {
task: Task,
// индекс сообщения; используется с буфером `INPUTS`
index: u8,
}
// память, зарезервированная для хранения сообщений, переданных `baz`
static mut baz_INPUTS: [MaybeUninit<u64>; 2] =
[MaybeUninit::uninit(), MaybeUninit::uninit()];
// список свободной памяти: используется для отслеживания свободных ячеек в массиве `baz_INPUTS`
// эта очередь инициализируется значениями `0` и `1` перед запуском `init`
static mut baz_FQ: Queue<u8, U2> = Queue::new();
// Поиск максимального приоритета для конечного потребителя `baz_FQ`
const baz_FQ_CEILING: u8 = 2;
impl<'a> foo::Spawn<'a> {
/// Spawns the `baz` task
pub fn baz(&self, message: u64) -> Result<(), u64> {
unsafe {
match lock(self.priority(), baz_FQ_CEILING, || {
baz_FQ.split().1.dequeue()
}) {
Some(index) => {
// ПРИМЕЧАНИЕ: `index` - владеющий указатель на ячейку буфера
baz_INPUTS[index as usize].write(message);
lock(self.priority(), RQ1_CEILING, || {
// помещаем задачу в очередь готовности
RQ1.split().1.enqueue_unchecked(Ready {
task: T1::baz,
index,
});
});
// вызываем прерывание, которое запускает диспетчер задач
rtic::pend(Interrupt::UART0);
}
None => {
// достигнута максимальная вместительность; неудачный вызов
Err(message)
}
}
}
}
}
}
```
А теперь давайте взглянем на настоящую реализацию диспетчера задач:
``` rust
mod app {
// ..
#[no_mangle]
unsafe UART1() {
const PRIORITY: u8 = 1;
let snapshot = basepri::read();
while let Some(ready) = RQ1.split().1.dequeue() {
match ready.task {
Task::baz => {
// ПРИМЕЧАНИЕ: `index` - владеющий указатель на ячейку буфера
let input = baz_INPUTS[ready.index as usize].read();
// сообщение было прочитано, поэтому можно вернуть ячейку обратно
// чтобы освободить очередь
// (диспетчер задач имеет эксклюзивный доступ к
// последнему элементу очереди)
baz_FQ.split().0.enqueue_unchecked(ready.index);
let priority = Cell::new(PRIORITY);
baz(baz::Context::new(&priority), input)
}
Task::bar => {
// выглядит также как ветка для `baz`
}
}
}
// инвариант BASEPRI
basepri::write(snapshot);
}
}
```
`INPUTS` плюс `FQ`, список свободной памяти равняется эффективному пулу памяти.
Однако, вместо того *список свободной памяти* (связный список), чтобы отслеживать
пустые ячейки в буфере `INPUTS`, мы используем SPSC очередь; это позволяет нам
уменьшить количество критических секций.
На самом деле благодаря этому выбору код диспетчера задач неблокируемый.
## Вместительность очереди
Фреймворк RTIC использует несколько очередей, такие как очереди готовности и
списки свободной памяти. Когда список свободной памяти пуст, попытка выызова
(`spawn`) задачи приводит к ошибке; это условие проверяется во время выполнения.
Не все операции, произвожимые фреймворком с этими очередями проверяют их
пустоту / наличие места. Например, возвращение ячейки списка свободной памяти
(см. диспетчер задач) не проверяется, поскольку есть фиксированное количество
таких ячеек циркулирующих в системе, равное вместительности списка свободной памяти.
Аналогично, добавление записи в очередь готовности (см. `Spawn`) не проверяется,
потому что вместительность очереди выбрана фреймворком.
Пользователи могут задавать вместительность программных задач;
эта вместительность - максимальное количество сообщений, которые можно
послать указанной задаче от задачи более высоким приоритетом до того,
как `spawn` вернет ошибку. Эта определяемая пользователем иместительность -
размер списка свободной памяти задачи (например `foo_FQ`), а также размер массива,
содержащего входные данные для задачи (например `foo_INPUTS`).
Вместительность очереди готовности (например `RQ1`) вычисляется как *сумма*
вместительностей всех задач, управляемх диспетчером; эта сумма является также
количеством сообщений, которые очередь может хранить в худшем сценарии, когда
все возможные сообщения были посланы до того, как диспетчер задач получает шанс
на запуск. По этой причине получение ячейки списка свободной памяти при любой
операции `spawn` приводит к тому, что очередь готовности еще не заполнена,
поэтому вставка записи в список готовности может пропустить проверку "полна ли очередь?".
В нашем запущенном примере задача `bar` не принимает входных данных, поэтому
мы можем пропустить проверку как `bar_INPUTS`, так и `bar_FQ` и позволить
пользователю посылать неограниченное число сообщений задаче, но если бы мы сделали это,
было бы невозможно превысить вместительность для `RQ1`, что позволяет нам
пропустить проверку "полна ли очередь?" при вызове задачи `baz`.
В разделе о [очереди таймера](timer-queue.html) мы увидим как
список свободной памяти используется для задач без входных данных.
## Анализ приоритетов
Очереди, использемые внутри интерфейса `spawn`, рассматриваются как обычные ресурсы
и для них тоже работает анализ приоритетов. Важно заметить, что это SPSC очереди,
и только один из конечных элементов становится ресурсом; другим конечным элементом
владеет диспетчер задач.
Рассмотрим следующий пример:
``` rust
#[rtic::app(device = ..)]
mod app {
#[idle(spawn = [foo, bar])]
fn idle(c: idle::Context) -> ! {
// ..
}
#[task]
fn foo(c: foo::Context) {
// ..
}
#[task]
fn bar(c: bar::Context) {
// ..
}
#[task(priority = 2, spawn = [foo])]
fn baz(c: baz::Context) {
// ..
}
#[task(priority = 3, spawn = [bar])]
fn quux(c: quux::Context) {
// ..
}
}
```
Вот как будет проходить анализ приоритетов:
- `idle` (prio = 0) и `baz` (prio = 2) соревнуются за конечный потребитель
`foo_FQ`; это приводит к максимальному приоритету `2`.
- `idle` (prio = 0) и `quux` (prio = 3) соревнуются за конечный потребитель
`bar_FQ`; это приводит к максимальному приоритету `3`.
- `idle` (prio = 0), `baz` (prio = 2) и `quux` (prio = 3) соревнуются за
конечный производитель `RQ1`; это приводит к максимальному приоритету `3`

372
book/ru/src/internals/timer-queue.md
View file

@ -1,372 +0,0 @@
# Очередь таймера
Функциональность очередь таймера позволяет пользователю планировать задачи на запуск
в опреленное время в будущем. Неудивительно, что эта функция также реализуется с помощью очереди:
очередь приоритетов, где запланированные задачи сортируются в порядке аозрастания времени.
Эта функция требует таймер, способный устанавливать прерывания истечения времени.
Таймер используется для пуска прерывания, когда настает запланированное время задачи;
в этот момент задача удаляется из очереди таймера и помещается в очередь готовности.
Давайте посмотрим, как это реализовано в коде. Рассмотрим следующую программу:
``` rust
#[rtic::app(device = ..)]
mod app {
// ..
#[task(capacity = 2, schedule = [foo])]
fn foo(c: foo::Context, x: u32) {
// запланировать задачу на повторный запуск через 1 млн. тактов
c.schedule.foo(c.scheduled + Duration::cycles(1_000_000), x + 1).ok();
}
extern "C" {
fn UART0();
}
}
```
## `schedule`
Давайте сначала взглянем на интерфейс `schedule`.
``` rust
mod foo {
pub struct Schedule<'a> {
priority: &'a Cell<u8>,
}
impl<'a> Schedule<'a> {
// `unsafe` и спрятано, потому что мы не хотим, чтобы пользовать сюда вмешивался
#[doc(hidden)]
pub unsafe fn priority(&self) -> &Cell<u8> {
self.priority
}
}
}
mod app {
type Instant = <path::to::user::monotonic::timer as rtic::Monotonic>::Instant;
// все задачи, которые могут быть запланированы (`schedule`)
enum T {
foo,
}
struct NotReady {
index: u8,
instant: Instant,
task: T,
}
// Очередь таймера - двоичная куча (min-heap) задач `NotReady`
static mut TQ: TimerQueue<U2> = ..;
const TQ_CEILING: u8 = 1;
static mut foo_FQ: Queue<u8, U2> = Queue::new();
const foo_FQ_CEILING: u8 = 1;
static mut foo_INPUTS: [MaybeUninit<u32>; 2] =
[MaybeUninit::uninit(), MaybeUninit::uninit()];
static mut foo_INSTANTS: [MaybeUninit<Instant>; 2] =
[MaybeUninit::uninit(), MaybeUninit::uninit()];
impl<'a> foo::Schedule<'a> {
fn foo(&self, instant: Instant, input: u32) -> Result<(), u32> {
unsafe {
let priority = self.priority();
if let Some(index) = lock(priority, foo_FQ_CEILING, || {
foo_FQ.split().1.dequeue()
}) {
// `index` - владеющий укачатель на ячейки в этих буферах
foo_INSTANTS[index as usize].write(instant);
foo_INPUTS[index as usize].write(input);
let nr = NotReady {
index,
instant,
task: T::foo,
};
lock(priority, TQ_CEILING, || {
TQ.enqueue_unchecked(nr);
});
} else {
// Не осталось места, чтобы разместить входные данные / instant
Err(input)
}
}
}
}
}
```
Это очень похоже на реализацию `Spawn`. На самом деле одни и те же буфер
`INPUTS` и список сободной памяти (`FQ`) используются совместно интерфейсами
`spawn` и `schedule`. Главное отличие между ними в том, что `schedule` также
размещает `Instant`, момент на который задача запланирована на запуск,
в отдельном буфере (`foo_INSTANTS` в нашем случае).
`TimerQueue::enqueue_unchecked` делает немного больше работы, чем
просто добавление записи в min-heap: он также вызывает прерывание
системного таймера (`SysTick`), если новая запись оказывается первой в очереди.
## Системный таймер
Прерывание системного таймера (`SysTick`) заботится о двух вещах:
передаче задач, которых становятся готовыми из очереди таймера в очередь готовности
и установке прерывания истечения времени, когда наступит запланированное
время следующей задачи.
Давайте посмотрим на соответствующий код.
``` rust
mod app {
#[no_mangle]
fn SysTick() {
const PRIORITY: u8 = 1;
let priority = &Cell::new(PRIORITY);
while let Some(ready) = lock(priority, TQ_CEILING, || TQ.dequeue()) {
match ready.task {
T::foo => {
// переместить эту задачу в очередь готовности `RQ1`
lock(priority, RQ1_CEILING, || {
RQ1.split().0.enqueue_unchecked(Ready {
task: T1::foo,
index: ready.index,
})
});
// вызвать диспетчер задач
rtic::pend(Interrupt::UART0);
}
}
}
}
}
```
Выглядит похоже на диспетчер задач, за исключением того, что
вместо запуска готовой задачи, она лишь переносится в очередь готовности,
что ведет к ее запуску с нужным приоритетом.
`TimerQueue::dequeue` установит новое прерывание истечения времени, если вернет
`None`. Он сязан с `TimerQueue::enqueue_unchecked`, который вызывает это
прерывание; на самом деле, `enqueue_unchecked` передает задачу установки
нового прерывание истечения времени обработчику `SysTick`.
## Точность и диапазон `cyccnt::Instant` и `cyccnt::Duration`
RTIC предоставляет реализацию `Monotonic`, основанную на счетчике тактов `DWT` (Data Watchpoint and Trace). `Instant::now` возвращает снимок таймера; эти снимки
DWT (`Instant`ы) используются для сортировки записей в очереди таймера.
Счетчик тактов - 32-битный счетчик, работающий на частоте ядра.
Этот счетчик обнуляется каждые `(1 << 32)` тактов; у нас нет прерывания,
ассоциированног с этим счетчиком, поэтому ничего ужасного не случится,
когда он пройдет оборот.
Чтобы упорядочить `Instant`ы в очереди, нам нужно сравнить 32-битные целые.
Чтобы учесть обороты, мы используем разницу между двумя `Instant`ами, `a - b`,
и рассматриваем результат как 32-битное знаковое целое.
Если результат меньше нуля, значит `b` более поздний `Instant`;
если результат больше нуля, значит `b` более ранний `Instant`.
Это значит, что планирование задачи на `Instant`, который на `(1 << 31) - 1` тактов
больше, чем запланированное время (`Instant`) первой (самой ранней) записи
в очереди приведет к тому, что задача будет помещена в неправильное
место в очереди. У нас есть несколько debug assertions в коде, чтобы
предотвратить эту пользовательскую ошибку, но этого нельзя избежать,
поскольку пользователь может написать
`(instant + duration_a) + duration_b` и переполнить `Instant`.
Системный таймер, `SysTick` - 24-битный счетчик также работающий
на частоте процессора. Когда следующая планируемая задача более, чем в
`1 << 24` тактов в будущем, прерывание устанавливается на время в пределах
`1 << 24` тактов. Этот процесс может происходить несколько раз, пока
следующая запланированная задача не будет в диапазоне счетчика `SysTick`.
Подведем итог, оба `Instant` и `Duration` имеют разрешение 1 такт ядра, и `Duration` эффективно имеет (полуоткрытый) диапазон `0..(1 << 31)` (не включая максимум) тактов ядра.
## Вместительность очереди
Вместительность очереди таймера рассчитывается как сумма вместительностей
всех планируемых (`schedule`) задач. Как и в случае очередей готовности,
это значит, что как только мы затребовали пустую ячейку в буфере `INPUTS`,
мы гарантируем, что способны передать задачу в очередь таймера;
это позволяет нам опустить проверки времени выполнения.
## Приоритет системного таймера
Приориет системного таймера не может быть установлен пользователем;
он выбирается фреймворком.
Чтобы убедиться, что низкоприоритетные задачи не препятствуют
запуску высокоприоритетных, мы выбираем приоритет системного таймера
максимальным из всех планируемых задач.
Чтобы понять, почему это нужно, рассмотрим вариант, когда две ранее
запланированные задачи с приоритетами `2` и `3` становятся готовыми в
примерно одинаковое время, но низкоприоритетная задача перемещается
в очередь готовности первой.
Если бы приоритет системного таймера был, например, равен `1`,
тогда после перемещения низкоприоритетной (`2`) задачи, это бы привело
к завершению (из-за того, что приоритет выше приоритета системного таймера)
ожидания выполнения высокоприоритетной задачи (`3`).
Чтобы избежать такого сценария, системный таймер должен работать на
приоритете, равном наивысшему из приоритетов планируемых задач;
в этом примере это `3`.
## Анализ приоритетов
Очередь таймера - это ресурс, разделяемый всеми задачами, которые могут
планировать (`schedule`) задачи и обработчиком `SysTick`.
Также интерфейс `schedule` соперничает с интерфейсом `spawn`
за списки свободной памяти. Все это должно уситываться в анализе приоритетов.
Чтобы проиллюстрировать, рассмотрим следующий пример:
``` rust
#[rtic::app(device = ..)]
mod app {
#[task(priority = 3, spawn = [baz])]
fn foo(c: foo::Context) {
// ..
}
#[task(priority = 2, schedule = [foo, baz])]
fn bar(c: bar::Context) {
// ..
}
#[task(priority = 1)]
fn baz(c: baz::Context) {
// ..
}
}
```
Анализ приоритетов происходил бы вот так:
- `foo` (prio = 3) и `baz` (prio = 1) планируемые задачи, поэтому
`SysTick` должен работать на максимальном из этих двух приоритетов, т.е. `3`.
- `foo::Spawn` (prio = 3) и `bar::Schedule` (prio = 2) соперничают за
конечный потребитель `baz_FQ`; это приводит к максимальному приоритету `3`.
- `bar::Schedule` (prio = 2) имеет экслюзивный доступ к
конечному потребителю `foo_FQ`; поэтому максимальный приоритет `foo_FQ` фактически `2`.
- `SysTick` (prio = 3) и `bar::Schedule` (prio = 2) соперничают за
очередь таймера `TQ`; это приводит к максимальному приоритету `3`.
- `SysTick` (prio = 3) и `foo::Spawn` (prio = 3) оба имеют неблокируемый
доступ к очереди готовности `RQ3`, что хранит записи `foo`;
поэтому максимальный приоритет `RQ3` фактически `3`.
- `SysTick` имеет эксклюзивный доступ к очереди готовности `RQ1`,
которая хранит записи `baz`; поэтому максимальный приоритет `RQ1` фактически `3`.
## Изменения в реализации `spawn`
Когда интерфейс `schedule` используется, реализация `spawn` немного
изменяется, чтобы отслеживать baseline задач. Как можете видеть в
реализации `schedule` есть буферы `INSTANTS`, используемые, чтобы
хранить время, в которое задача была запланирована навыполнение;
этот `Instant` читается диспетчером задач и передается в пользовательский
код, как часть контекста задачи.
``` rust
mod app {
// ..
#[no_mangle]
unsafe UART1() {
const PRIORITY: u8 = 1;
let snapshot = basepri::read();
while let Some(ready) = RQ1.split().1.dequeue() {
match ready.task {
Task::baz => {
let input = baz_INPUTS[ready.index as usize].read();
// ADDED
let instant = baz_INSTANTS[ready.index as usize].read();
baz_FQ.split().0.enqueue_unchecked(ready.index);
let priority = Cell::new(PRIORITY);
// ИЗМЕНЕНО instant передан как часть контекста задачи
baz(baz::Context::new(&priority, instant), input)
}
Task::bar => {
// выглядит также как ветка для `baz`
}
}
}
// инвариант BASEPRI
basepri::write(snapshot);
}
}
```
И наоборот, реализации `spawn` нужно писать значение в буфер `INSTANTS`.
Записанное значение располагается в структуре `Spawn` и это либо
время `start` аппаратной задачи, либо время `scheduled` программной задачи.
``` rust
mod foo {
// ..
pub struct Spawn<'a> {
priority: &'a Cell<u8>,
// ADDED
instant: Instant,
}
impl<'a> Spawn<'a> {
pub unsafe fn priority(&self) -> &Cell<u8> {
&self.priority
}
// ADDED
pub unsafe fn instant(&self) -> Instant {
self.instant
}
}
}
mod app {
impl<'a> foo::Spawn<'a> {
/// Spawns the `baz` task
pub fn baz(&self, message: u64) -> Result<(), u64> {
unsafe {
match lock(self.priority(), baz_FQ_CEILING, || {
baz_FQ.split().1.dequeue()
}) {
Some(index) => {
baz_INPUTS[index as usize].write(message);
// ADDED
baz_INSTANTS[index as usize].write(self.instant());
lock(self.priority(), RQ1_CEILING, || {
RQ1.split().1.enqueue_unchecked(Ready {
task: Task::foo,
index,
});
});
rtic::pend(Interrupt::UART0);
}
None => {
// достигнута максимальная вместительность; неудачный вызов
Err(message)
}
}
}
}
}
}
```

4
book/ru/src/migration.md
View file

@ -1,4 +0,0 @@
# Инструкции по миграции
В этом разделе описывается как мигрировать между различными версиями RTIC.
Можно также использовать для сравнения версий.

48
book/ru/src/migration/migration_rtic.md
View file

@ -1,48 +0,0 @@
# Миграция с RTFM на RTIC
В этом разделе описано, как обновить приложение, написанное на RTFM v0.5.x на RTIC той же версии.
Это необходимо из-за переименования фреймворка в соответствии с [RFC #33].
**Примечание:** Между RTFM v0.5.3 и RTIC v0.5.3 нет разниц в коде, это исключительно изменение имен.
[RFC #33]: https://github.com/rtic-rs/rfcs/pull/33
## `Cargo.toml`
Во-первых, зависимость `cortex-m-rtfm` должна быть изменена на `cortex-m-rtic`.
``` toml
[dependencies]
# измените это
cortex-m-rtfm = "0.5.3"
# на это
cortex-m-rtic = "0.5.3"
```
## Изменения в коде
Единственное изменение в коде, которое нужно сделать - поменять все ссылки на `rtfm`,
чтобы они указывали на `rtic`:
``` rust
//
// Измените это
//
#[rtfm::app(/* .. */, monotonic = rtfm::cyccnt::CYCCNT)]
const APP: () = {
// ...
};
//
// На это
//
#[rtic::app(/* .. */, monotonic = rtic::cyccnt::CYCCNT)]
const APP: () = {
// ...
};
```

230
book/ru/src/migration/migration_v4.md
View file

@ -1,230 +0,0 @@
# Миграция с v0.4.x на v0.5.0
Этот раздел описывает как обновить программы, написанные на RTIC v0.4.x
на версию v0.5.0 фреймворка.
## `Cargo.toml`
Во-первых, нужно обновить версию зависимости `cortex-m-rtic` до
`"0.5.0"`. Опцию `timer-queue` нужно удалить.
``` toml
[dependencies.cortex-m-rtic]
# изменить это
version = "0.4.3"
# на это
version = "0.5.0"
# и удалить Cargo feature
features = ["timer-queue"]
# ^^^^^^^^^^^^^
```
## Аргумент `Context`
Все функции внутри элемента `#[rtic::app]` должны принимать первым аргументом
структуру `Context`. Этот тип `Context` будет содержать переменные, которые были магически
инъецированы в область видимости функции версией v0.4.x фреймворка:
`resources`, `spawn`, `schedule` -- эти переменные станут полями структуры `Context`.
Каждая функция элемента `#[rtic::app]` получит отдельный тип `Context`.
``` rust
#[rtic::app(/* .. */)]
const APP: () = {
// change this
#[task(resources = [x], spawn = [a], schedule = [b])]
fn foo() {
resources.x.lock(|x| /* .. */);
spawn.a(message);
schedule.b(baseline);
}
// into this
#[task(resources = [x], spawn = [a], schedule = [b])]
fn foo(mut cx: foo::Context) {
// ^^^^^^^^^^^^^^^^^^^^
cx.resources.x.lock(|x| /* .. */);
// ^^^
cx.spawn.a(message);
// ^^^
cx.schedule.b(message, baseline);
// ^^^
}
// change this
#[init]
fn init() {
// ..
}
// into this
#[init]
fn init(cx: init::Context) {
// ^^^^^^^^^^^^^^^^^
// ..
}
// ..
};
```
## Ресурсы
Синтаксис, используемый, для определения ресурсов был изменен с переменных `static mut`
на структуру `Resources`.
``` rust
#[rtic::app(/* .. */)]
const APP: () = {
// измените это
static mut X: u32 = 0;
static mut Y: u32 = (); // поздний ресурс
// на это
struct Resources {
#[init(0)] // <- начальное значение
X: u32, // ПРИМЕЧАНИЕ: мы предлагаем изменить стиль именования на `snake_case`
Y: u32, // поздний ресурс
}
// ..
};
```
## Периферия устройства
Если ваша программа получала доступ к периферии в `#[init]` через
переменну `device`, вам нужно будет добавить `peripherals = true` в атрибут
`#[rtic::app]`, чтобы и дальше получать доступ к периферии через поле `device` структуры `init::Context`.
Измените это:
``` rust
#[rtic::app(/* .. */)]
const APP: () = {
#[init]
fn init() {
device.SOME_PERIPHERAL.write(something);
}
// ..
};
```
На это:
``` rust
#[rtic::app(/* .. */, peripherals = true)]
// ^^^^^^^^^^^^^^^^^^
const APP: () = {
#[init]
fn init(cx: init::Context) {
// ^^^^^^^^^^^^^^^^^
cx.device.SOME_PERIPHERAL.write(something);
// ^^^
}
// ..
};
```
## `#[interrupt]` и `#[exception]`
Атрибуты `#[interrupt]` и `#[exception]` были удалены. Чтобы определять аппаратные задачи в v0.5.x
используте атрибут `#[task]` с аргументом `binds`.
Измените это:
``` rust
#[rtic::app(/* .. */)]
const APP: () = {
// аппаратные задачи
#[exception]
fn SVCall() { /* .. */ }
#[interrupt]
fn UART0() { /* .. */ }
// программные задачи
#[task]
fn foo() { /* .. */ }
// ..
};
```
На это:
``` rust
#[rtic::app(/* .. */)]
const APP: () = {
#[task(binds = SVCall)]
// ^^^^^^^^^^^^^^
fn svcall(cx: svcall::Context) { /* .. */ }
// ^^^^^^ мы предлагаем использовать `snake_case` имя здесь
#[task(binds = UART0)]
// ^^^^^^^^^^^^^
fn uart0(cx: uart0::Context) { /* .. */ }
#[task]
fn foo(cx: foo::Context) { /* .. */ }
// ..
};
```
## `schedule`
Интерфейс `schedule` больше не требует cargo опции `timer-queue`, которая была удалена.
Чтобы использовать интерфес `schedule`, нужно сначала определить
монотонный тамер, который будет использоваьт среды выполнения, с помощью аргумента `monotonic`
атрибута `#[rtic::app]`. Чтобы продолжить использовать счетчик циклов
(CYCCNT) в качестве монотонного таймера, как было в версии v0.4.x, добавьте
аргумент `monotonic = rtic::cyccnt::CYCCNT` в атрибут `#[rtic::app]`.
Также были добавлены типы `Duration` и `Instant`, а трейт `U32Ext` был перемещен в модуль `rtic::cyccnt`.
Этот модуль доступен только на устройствах ARMv7-M+.
Удаление `timer-queue` также возвращает периферию `DWT` в структуру периферии ядра,
включить ее в работу можно внутри `init`.
Измените это:
``` rust
use rtic::{Duration, Instant, U32Ext};
#[rtic::app(/* .. */)]
const APP: () = {
#[task(schedule = [b])]
fn a() {
// ..
}
};
```
На это:
``` rust
use rtic::cyccnt::{Duration, Instant, U32Ext};
// ^^^^^^^^
#[rtic::app(/* .. */, monotonic = rtic::cyccnt::CYCCNT)]
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
const APP: () = {
#[init]
fn init(cx: init::Context) {
cx.core.DWT.enable_cycle_counter();
// опционально, настройка запуска DWT без подключенного отладчика
cx.core.DCB.enable_trace();
}
#[task(schedule = [b])]
fn a(cx: a::Context) {
// ..
}
};
```

208
book/ru/src/migration/migration_v5.md
View file

@ -1,208 +0,0 @@
# Миграция с v0.5.x на v0.6.0
Этот раздел описывает как обновиться с версии v0.5.x на v0.6.0 фреймворка RTIC.
## `Cargo.toml` - увеличьте версию
Измените версию `cortex-m-rtic` на `"0.6.0"`.
## `mod` вместо `const`
С поддержкой атрибутов над модулями трюк с `const APP` теперь не нужен.
Измените
``` rust
#[rtic::app(/* .. */)]
const APP: () = {
[код здесь]
};
```
на
``` rust
#[rtic::app(/* .. */)]
mod app {
[код здесь]
}
```
Так как теперь используется обычный модуль Rust, это значит, что можно использовать
обычный пользовательский код в этом модуле.
Также жто значит, что `use`-выражения для ресурсов (и т.п.) могут понадобиться.
## Перенос диспетчеров из `extern "C"` в аргументы app.
Измените
``` rust
#[rtic::app(/* .. */)]
const APP: () = {
[код здесь]
// RTIC требует, чтобы неиспользуемые прерывания были задекларированы в блоке extern, когда
// используются программные задачи; эти свободные прерывания будут использованы для управления
// программными задачами.
extern "C" {
fn SSI0();
fn QEI0();
}
};
```
на
``` rust
#[rtic::app(/* .. */, dispatchers = [SSI0, QEI0])]
mod app {
[код здесь]
}
```
Это работает и для ОЗУ-функций, см. examples/ramfunc.rs
## Init всегда возвращает поздние ресурсы
С целью сделать API более симметричным задача #[init] всегда возвращает поздние ресурсы.
С этого:
``` rust
#[rtic::app(device = lm3s6965)]
mod app {
#[init]
fn init(_: init::Context) {
rtic::pend(Interrupt::UART0);
}
// [еще код]
}
```
на это:
``` rust
#[rtic::app(device = lm3s6965)]
mod app {
#[init]
fn init(_: init::Context) -> init::LateResources {
rtic::pend(Interrupt::UART0);
init::LateResources {}
}
// [еще код]
}
```
## Структура Resources - `#[resources]`
Ранее ресурсы RTIC должны были располагаться в структуре с именем "Resources":
``` rust
struct Resources {
// Ресурсы определены здесь
}
```
В RTIC v0.6.0 структура ресурсов аннотируется также, как и
`#[task]`, `#[init]`, `#[idle]`: атрибутом `#[resources]`
``` rust
#[resources]
struct Resources {
// Ресурсы определены здесь
}
```
На самом деле, имя структуры предоставлено на усмотрение разработчика:
``` rust
#[resources]
struct Whateveryouwant {
// Ресурсы определены здесь
}
```
будет работать так же хороршо.
## Вызов/планирование откуда угодно
С этой новой возвожностью, старый код, такой как:
``` rust
#[task(spawn = [bar])]
fn foo(cx: foo::Context) {
cx.spawn.bar().unwrap();
}
#[task(schedule = [bar])]
fn bar(cx: bar::Context) {
cx.schedule.foo(/* ... */).unwrap();
}
```
Теперь будет выглядеть так:
``` rust
#[task]
fn foo(_c: foo::Context) {
bar::spawn().unwrap();
}
#[task]
fn bar(_c: bar::Context) {
foo::schedule(/* ... */).unwrap();
}
```
Заметьте, что атрибуты `spawn` и `schedule` больше не нужны.
## Симметричные блокировки
Теперь RTIC использует симметричные блокировки, это значит, что метод `lock` нужно использовать для
всех доступов к ресурсам. Поскольку высокоприоритетные задачи имеют эксклюзивный доступ к ресурсу,
в старом коде можно было следующее:
``` rust
#[task(priority = 2, resources = [r])]
fn foo(cx: foo::Context) {
cx.resources.r = /* ... */;
}
#[task(resources = [r])]
fn bar(cx: bar::Context) {
cx.resources.r.lock(|r| r = /* ... */);
}
```
С симметричными блокировками нужно вызывать `lock` для обоих задач:
``` rust
#[task(priority = 2, resources = [r])]
fn foo(cx: foo::Context) {
cx.resources.r.lock(|r| r = /* ... */);
}
#[task(resources = [r])]
fn bar(cx: bar::Context) {
cx.resources.r.lock(|r| r = /* ... */);
}
```
Заметьте, что скорость работы не изменяется благодаря оптимизациям LLVM, которые убирают ненужные блокировки.
---
## Дополнительно
### Внешние задачи
Как программные, так и аппаратные задачи теперь можно определять вне модуля `mod app`.
Ранее это было возможно только путем реализации обертки, вызывающей реализацию задачи.
Смотреть примеры `examples/extern_binds.rs` и `examples/extern_spawn.rs`.

26
book/ru/src/preface.md
View file

@ -1,26 +0,0 @@
<div align="center"><img width="300" height="300" src="RTIC.svg"></div>
<div style="font-size: 6em; font-weight: bolder;" align="center">RTIC</div>
<h1 align="center">Real-Time Interrupt-driven Concurrency</h1>
<p align="center">Конкурентный фреймворк для создания систем реального времени</p>
# Введение
Эта книга содержит документацию пользовательского уровня о фреймворке Real-Time Interrupt-driven Concurrency
(RTIC). Справочник по API можно найти [здесь](../../api/).
Также известен как Real-Time For the Masses.
<!--Оригинал данного руководства на [английском].-->
<!--[английском]: ../en/index.html-->
Это документация по RTIC версии v0.6.x; за документацией по другим версиям:
* v0.5.x [сюда](/0.5).
* v0.4.x [сюда](/0.4).
{{#include ../../../README_ru.md:7:45}}
{{#include ../../../README_ru.md:51:}}

22
build.rs
View file

@ -1,22 +0,0 @@
use std::env;
fn main() {
let target = env::var("TARGET").unwrap();
if version_check::Channel::read().unwrap().is_nightly() {
println!("cargo:rustc-cfg=rustc_is_nightly")
}
if target.starts_with("thumbv6m") {
println!("cargo:rustc-cfg=armv6m")
}
if target.starts_with("thumbv7m")
| target.starts_with("thumbv7em")
| target.starts_with("thumbv8m")
{
println!("cargo:rustc-cfg=armv7m")
}
println!("cargo:rerun-if-changed=build.rs");
}

4
ci/expected/baseline.run
View file

@ -1,4 +0,0 @@
init(baseline = Instant(0))
foo(baseline = Instant(0))
UART0(baseline = Instant(904))
foo(baseline = Instant(904))

2
ci/expected/cfg.run
View file

@ -1,2 +0,0 @@
foo has been called 1 time
foo has been called 2 times

4
ci/expected/multilock.run
View file

@ -1,4 +0,0 @@
Multiple single locks
Multiple single locks, s1: 1, s2: 1, s3: 1
Multilock!
Multiple single locks, s1: 2, s2: 2, s3: 2

2
ci/expected/only-shared-access.run
View file

@ -1,2 +0,0 @@
UART1(key = 0xdeadbeef)
UART0(key = 0xdeadbeef)

3
ci/expected/periodic.run
View file

@ -1,3 +0,0 @@
foo(scheduled = Instant(8000000), now = Instant(8000196))
foo(scheduled = Instant(16000000), now = Instant(16000196))
foo(scheduled = Instant(24000000), now = Instant(24000196))

2
ci/expected/pool.run
View file

@ -1,2 +0,0 @@
bar(0x2000008c)
foo(0x20000110)

5
ci/expected/preempt.run
View file

@ -1,5 +0,0 @@
GPIOA - start
GPIOC - start
GPIOC - end
GPIOB
GPIOA - end

1
ci/expected/ramfunc.grep.bar
View file

@ -1 +0,0 @@
20000000 t ramfunc::bar::h9d6714fe5a3b0c89

1
ci/expected/ramfunc.grep.foo
View file

@ -1 +0,0 @@
00000162 t ramfunc::foo::h30e7789b08c08e19

2
ci/expected/resource.run
View file

@ -1,2 +0,0 @@
UART1: shared = 1
UART0: shared = 2

3
ci/expected/schedule.run
View file

@ -1,3 +0,0 @@
init @ Instant(0)
bar @ Instant(4000236)
foo @ Instant(8000173)

2
ci/expected/singleton.run
View file

@ -1,2 +0,0 @@
bar(2)
foo(1)

49
examples/capacity.rs
View file

@ -1,49 +0,0 @@
//! examples/capacity.rs
#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]
use panic_semihosting as _;
#[rtic::app(device = lm3s6965, dispatchers = [SSI0])]
mod app {
use cortex_m_semihosting::{debug, hprintln};
use lm3s6965::Interrupt;
#[shared]
struct Shared {}
#[local]
struct Local {}
#[init]
fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {
rtic::pend(Interrupt::UART0);
(Shared {}, Local {}, init::Monotonics())
}
#[task(binds = UART0)]
fn uart0(_: uart0::Context) {
foo::spawn(0).unwrap();
foo::spawn(1).unwrap();
foo::spawn(2).unwrap();
foo::spawn(3).unwrap();
bar::spawn().unwrap();
}
#[task(capacity = 4)]
fn foo(_: foo::Context, x: u32) {
hprintln!("foo({})", x).unwrap();
}
#[task]
fn bar(_: bar::Context) {
hprintln!("bar").unwrap();
debug::exit(debug::EXIT_SUCCESS);
}
}

96
examples/cfg-whole-task.rs
View file

@ -1,96 +0,0 @@
//! examples/cfg-whole-task.rs
#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]
use panic_semihosting as _;
#[rtic::app(device = lm3s6965, dispatchers = [SSI0, QEI0])]
mod app {
use cortex_m_semihosting::debug;
#[cfg(debug_assertions)]
use cortex_m_semihosting::hprintln;
#[shared]
struct Shared {
#[cfg(debug_assertions)] // <- `true` when using the `dev` profile
count: u32,
#[cfg(never)]
unused: u32,
}
#[local]
struct Local {}
#[init]
fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {
foo::spawn().unwrap();
foo::spawn().unwrap();
(
Shared {
#[cfg(debug_assertions)]
count: 0,
#[cfg(never)]
unused: 1,
},
Local {},
init::Monotonics(),
)
}
#[idle]
fn idle(_: idle::Context) -> ! {
debug::exit(debug::EXIT_SUCCESS);
loop {
cortex_m::asm::nop();
}
}
#[task(capacity = 2, shared = [count])]
fn foo(mut _cx: foo::Context) {
#[cfg(debug_assertions)]
{
_cx.shared.count.lock(|count| *count += 1);
log::spawn(_cx.shared.count.lock(|count| *count)).unwrap();
}
// this wouldn't compile in `release` mode
// *_cx.shared.count += 1;
// ..
}
// The whole task should disappear,
// currently still present in the Tasks enum
#[cfg(never)]
#[task(capacity = 2, shared = [count])]
fn foo2(mut _cx: foo2::Context) {
#[cfg(debug_assertions)]
{
_cx.shared.count.lock(|count| *count += 10);
log::spawn(_cx.shared.count.lock(|count| *count)).unwrap();
}
// this wouldn't compile in `release` mode
// *_cx.shared.count += 1;
// ..
}
#[cfg(debug_assertions)]
#[task(capacity = 2)]
fn log(_: log::Context, n: u32) {
hprintln!(
"foo has been called {} time{}",
n,
if n == 1 { "" } else { "s" }
)
.ok();
}
}

51
examples/destructure.rs
View file

@ -1,51 +0,0 @@
//! examples/destructure.rs
#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]
use panic_semihosting as _;
#[rtic::app(device = lm3s6965)]
mod app {
use cortex_m_semihosting::hprintln;
use lm3s6965::Interrupt;
#[shared]
struct Shared {
// Some resources to work with
a: u32,
b: u32,
c: u32,
}
#[local]
struct Local {}
#[init]
fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {
rtic::pend(Interrupt::UART0);
rtic::pend(Interrupt::UART1);
(Shared { a: 0, b: 0, c: 0 }, Local {}, init::Monotonics())
}
// Direct destructure
#[task(binds = UART0, shared = [&a, &b, &c])]
fn uart0(cx: uart0::Context) {
let a = cx.shared.a;
let b = cx.shared.b;
let c = cx.shared.c;
hprintln!("UART0: a = {}, b = {}, c = {}", a, b, c).unwrap();
}
// De-structure-ing syntax
#[task(binds = UART1, shared = [&a, &b, &c])]
fn uart1(cx: uart1::Context) {
let uart1::SharedResources { a, b, c } = cx.shared;
hprintln!("UART0: a = {}, b = {}, c = {}", a, b, c).unwrap();
}
}

46
examples/double_schedule.rs
View file

@ -1,46 +0,0 @@
//! examples/double_schedule.rs
#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]
use panic_semihosting as _;
#[rtic::app(device = lm3s6965, dispatchers = [SSI0])]
mod app {
use dwt_systick_monotonic::DwtSystick;
use rtic::time::duration::Seconds;
#[monotonic(binds = SysTick, default = true)]
type MyMono = DwtSystick<8_000_000>; // 8 MHz
#[shared]
struct Shared {}
#[local]
struct Local {}
#[init]
fn init(cx: init::Context) -> (Shared, Local, init::Monotonics) {
task1::spawn().ok();
let mut dcb = cx.core.DCB;
let dwt = cx.core.DWT;
let systick = cx.core.SYST;
let mono = DwtSystick::new(&mut dcb, dwt, systick, 8_000_000);
(Shared {}, Local {}, init::Monotonics(mono))
}
#[task]
fn task1(_cx: task1::Context) {
task2::spawn_after(Seconds(1_u32)).ok();
}
#[task]
fn task2(_cx: task2::Context) {
task1::spawn_after(Seconds(1_u32)).ok();
}
}

72
examples/lock.rs
View file

@ -1,72 +0,0 @@
//! examples/lock.rs
#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]
use panic_semihosting as _;
#[rtic::app(device = lm3s6965)]
mod app {
use cortex_m_semihosting::{debug, hprintln};
use lm3s6965::Interrupt;
#[shared]
struct Shared {
shared: u32,
}
#[local]
struct Local {}
#[init]
fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {
rtic::pend(Interrupt::GPIOA);
(Shared { shared: 0 }, Local {}, init::Monotonics())
}
// when omitted priority is assumed to be `1`
#[task(binds = GPIOA, shared = [shared])]
fn gpioa(mut c: gpioa::Context) {
hprintln!("A").unwrap();
// the lower priority task requires a critical section to access the data
c.shared.shared.lock(|shared| {
// data can only be modified within this critical section (closure)
*shared += 1;
// GPIOB will *not* run right now due to the critical section
rtic::pend(Interrupt::GPIOB);
hprintln!("B - shared = {}", *shared).unwrap();
// GPIOC does not contend for `shared` so it's allowed to run now
rtic::pend(Interrupt::GPIOC);
});
// critical section is over: GPIOB can now start
hprintln!("E").unwrap();
debug::exit(debug::EXIT_SUCCESS);
}
#[task(binds = GPIOB, priority = 2, shared = [shared])]
fn gpiob(mut c: gpiob::Context) {
// the higher priority task does still need a critical section
let shared = c.shared.shared.lock(|shared| {
*shared += 1;
*shared
});
hprintln!("D - shared = {}", shared).unwrap();
}
#[task(binds = GPIOC, priority = 3)]
fn gpioc(_: gpioc::Context) {
hprintln!("C").unwrap();
}
}

52
examples/message.rs
View file

@ -1,52 +0,0 @@
//! examples/message.rs
#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]
use panic_semihosting as _;
#[rtic::app(device = lm3s6965, dispatchers = [SSI0])]
mod app {
use cortex_m_semihosting::{debug, hprintln};
#[shared]
struct Shared {}
#[local]
struct Local {}
#[init]
fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {
foo::spawn(/* no message */).unwrap();
(Shared {}, Local {}, init::Monotonics())
}
#[task(local = [count: u32 = 0])]
fn foo(cx: foo::Context) {
hprintln!("foo").unwrap();
bar::spawn(*cx.local.count).unwrap();
*cx.local.count += 1;
}
#[task]
fn bar(_: bar::Context, x: u32) {
hprintln!("bar({})", x).unwrap();
baz::spawn(x + 1, x + 2).unwrap();
}
#[task]
fn baz(_: baz::Context, x: u32, y: u32) {
hprintln!("baz({}, {})", x, y).unwrap();
if x + y > 4 {
debug::exit(debug::EXIT_SUCCESS);
}
foo::spawn().unwrap();
}
}

86
examples/multilock.rs
View file

@ -1,86 +0,0 @@
//! examples/mutlilock.rs
//!
//! The multi-lock feature example.
#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]
use panic_semihosting as _;
#[rtic::app(device = lm3s6965)]
mod app {
use cortex_m_semihosting::{debug, hprintln};
use lm3s6965::Interrupt;
#[shared]
struct Shared {
shared1: u32,
shared2: u32,
shared3: u32,
}
#[local]
struct Local {}
#[init]
fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {
rtic::pend(Interrupt::GPIOA);
(
Shared {
shared1: 0,
shared2: 0,
shared3: 0,
},
Local {},
init::Monotonics(),
)
}
// when omitted priority is assumed to be `1`
#[task(binds = GPIOA, shared = [shared1, shared2, shared3])]
fn locks(c: locks::Context) {
let mut s1 = c.shared.shared1;
let mut s2 = c.shared.shared2;
let mut s3 = c.shared.shared3;
hprintln!("Multiple single locks").unwrap();
s1.lock(|s1| {
s2.lock(|s2| {
s3.lock(|s3| {
*s1 += 1;
*s2 += 1;
*s3 += 1;
hprintln!(
"Multiple single locks, s1: {}, s2: {}, s3: {}",
*s1,
*s2,
*s3
)
.unwrap();
})
})
});
hprintln!("Multilock!").unwrap();
(s1, s2, s3).lock(|s1, s2, s3| {
*s1 += 1;
*s2 += 1;
*s3 += 1;
hprintln!(
"Multiple single locks, s1: {}, s2: {}, s3: {}",
*s1,
*s2,
*s3
)
.unwrap();
});
debug::exit(debug::EXIT_SUCCESS);
}
}

53
examples/not-sync.rs
View file

@ -1,53 +0,0 @@
//! `examples/not-sync.rs`
// #![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]
use core::marker::PhantomData;
use panic_semihosting as _;
pub struct NotSync {
_0: PhantomData<*const ()>,
}
unsafe impl Send for NotSync {}
#[rtic::app(device = lm3s6965, dispatchers = [SSI0])]
mod app {
use super::NotSync;
use core::marker::PhantomData;
use cortex_m_semihosting::debug;
#[shared]
struct Shared {
shared: NotSync,
}
#[local]
struct Local {}
#[init]
fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {
debug::exit(debug::EXIT_SUCCESS);
(
Shared {
shared: NotSync { _0: PhantomData },
},
Local {},
init::Monotonics(),
)
}
#[task(shared = [&shared])]
fn foo(c: foo::Context) {
let _: &NotSync = c.shared.shared;
}
#[task(shared = [&shared])]
fn bar(c: bar::Context) {
let _: &NotSync = c.shared.shared;
}
}

43
examples/only-shared-access.rs
View file

@ -1,43 +0,0 @@
//! examples/static.rs
#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]
use panic_semihosting as _;
#[rtic::app(device = lm3s6965)]
mod app {
use cortex_m_semihosting::{debug, hprintln};
use lm3s6965::Interrupt;
#[shared]
struct Shared {
key: u32,
}
#[local]
struct Local {}
#[init]
fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {
rtic::pend(Interrupt::UART0);
rtic::pend(Interrupt::UART1);
(Shared { key: 0xdeadbeef }, Local {}, init::Monotonics())
}
#[task(binds = UART0, shared = [&key])]
fn uart0(cx: uart0::Context) {
let key: &u32 = cx.shared.key;
hprintln!("UART0(key = {:#x})", key).unwrap();
debug::exit(debug::EXIT_SUCCESS);
}
#[task(binds = UART1, priority = 2, shared = [&key])]
fn uart1(cx: uart1::Context) {
hprintln!("UART1(key = {:#x})", cx.shared.key).unwrap();
}
}

43
examples/periodic.rs
View file

@ -1,43 +0,0 @@
//! examples/periodic.rs
#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]
use panic_semihosting as _;
// NOTE: does NOT work on QEMU!
#[rtic::app(device = lm3s6965, dispatchers = [SSI0])]
mod app {
use dwt_systick_monotonic::DwtSystick;
use rtic::time::duration::Seconds;
#[monotonic(binds = SysTick, default = true)]
type MyMono = DwtSystick<8_000_000>; // 8 MHz
#[shared]
struct Shared {}
#[local]
struct Local {}
#[init]
fn init(cx: init::Context) -> (Shared, Local, init::Monotonics) {
let mut dcb = cx.core.DCB;
let dwt = cx.core.DWT;
let systick = cx.core.SYST;
let mono = DwtSystick::new(&mut dcb, dwt, systick, 8_000_000);
foo::spawn_after(Seconds(1_u32)).unwrap();
(Shared {}, Local {}, init::Monotonics(mono))
}
#[task]
fn foo(_cx: foo::Context) {
// Periodic
foo::spawn_after(Seconds(1_u32)).unwrap();
}
}

46
examples/preempt.rs
View file

@ -1,46 +0,0 @@
//! examples/preempt.rs
#![no_main]
#![no_std]
use panic_semihosting as _;
use rtic::app;
#[app(device = lm3s6965)]
mod app {
use cortex_m_semihosting::{debug, hprintln};
use lm3s6965::Interrupt;
#[shared]
struct Shared {}
#[local]
struct Local {}
#[init]
fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {
rtic::pend(Interrupt::GPIOA);
(Shared {}, Local {}, init::Monotonics())
}
#[task(binds = GPIOA, priority = 1)]
fn gpioa(_: gpioa::Context) {
hprintln!("GPIOA - start").unwrap();
rtic::pend(Interrupt::GPIOC);
hprintln!("GPIOA - end").unwrap();
debug::exit(debug::EXIT_SUCCESS);
}
#[task(binds = GPIOB, priority = 2)]
fn gpiob(_: gpiob::Context) {
hprintln!(" GPIOB").unwrap();
}
#[task(binds = GPIOC, priority = 2)]
fn gpioc(_: gpioc::Context) {
hprintln!(" GPIOC - start").unwrap();
rtic::pend(Interrupt::GPIOB);
hprintln!(" GPIOC - end").unwrap();
}
}

67
examples/resource.rs
View file

@ -1,67 +0,0 @@
//! examples/resource.rs
#![deny(unsafe_code)]
#![deny(warnings)]
#![no_main]
#![no_std]
use panic_semihosting as _;
#[rtic::app(device = lm3s6965)]
mod app {
use cortex_m_semihosting::{debug, hprintln};
use lm3s6965::Interrupt;
#[shared]
struct Shared {
shared: u32,
}
#[local]
struct Local {}
#[init]
fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {
rtic::pend(Interrupt::UART0);
rtic::pend(Interrupt::UART1);
(Shared { shared: 0 }, Local {}, init::Monotonics())
}
// `shared` cannot be accessed from this context
#[idle]
fn idle(_cx: idle::Context) -> ! {
debug::exit(debug::EXIT_SUCCESS);
// error: no `shared` field in `idle::Context`
// _cx.shared.shared += 1;
loop {
cortex_m::asm::nop();
}
}
// `shared` can be accessed from this context
// defaults to priority 1
#[task(binds = UART0, shared = [shared])]
fn uart0(mut cx: uart0::Context) {
let shared = cx.shared.shared.lock(|shared| {
*shared += 1;
*shared
});
hprintln!("UART0: shared = {}", shared).unwrap();
}
// `shared` can be accessed from this context
// explicitly set to priority 2
#[task(binds = UART1, shared = [shared], priority = 2)]
fn uart1(mut cx: uart1::Context) {
let shared = cx.shared.shared.lock(|shared| {
*shared += 1;
*shared
});
hprintln!("UART1: shared = {}", shared).unwrap();
}
}

Some files were not shown because too many files have changed in this diff Show more