diff options
| -rw-r--r-- | .github/dependabot.yml | 4 | ||||
| -rw-r--r-- | .github/workflows/audit.yaml | 2 | ||||
| -rw-r--r-- | .github/workflows/build.yml | 4 | ||||
| -rw-r--r-- | .github/workflows/changelog.yml | 2 | ||||
| -rw-r--r-- | Cargo.toml | 2 | ||||
| -rw-r--r-- | book/en/src/SUMMARY.md | 1 | ||||
| -rw-r--r-- | book/en/src/by-example/starting_a_project.md | 5 | ||||
| -rw-r--r-- | book/en/src/internals/targets.md | 71 | ||||
| -rw-r--r-- | xtask/Cargo.toml | 2 |
9 files changed, 86 insertions, 7 deletions
diff --git a/.github/dependabot.yml b/.github/dependabot.yml index d062b443..c3fda54f 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -4,7 +4,11 @@ updates: directory: "/" schedule: interval: "weekly" + labels: + - "skip-changelog" - package-ecosystem: "cargo" directory: "/" schedule: interval: "weekly" + labels: + - "skip-changelog" diff --git a/.github/workflows/audit.yaml b/.github/workflows/audit.yaml index abf0898b..1d6069d1 100644 --- a/.github/workflows/audit.yaml +++ b/.github/workflows/audit.yaml @@ -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 }} diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index ed7c0730..5e1467ca 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -233,7 +233,7 @@ jobs: uses: actions/checkout@v3 - name: Cache pip installed linkchecker - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: ~/.cache/pip key: ${{ runner.os }}-pip @@ -347,7 +347,7 @@ jobs: echo "versionmajor=$VERSIONMAJOR" >> $GITHUB_ENV echo "version=$VERSION" >> $GITHUB_ENV - - uses: everlytic/branch-merge@1.1.2 + - uses: everlytic/branch-merge@1.1.5 with: github_token: ${{ github.token }} source_ref: 'master' diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml index ccf6eb91..74b821da 100644 --- a/.github/workflows/changelog.yml +++ b/.github/workflows/changelog.yml @@ -16,7 +16,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout sources - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Check that changelog updated uses: dangoslen/changelog-enforcer@v3 @@ -37,7 +37,7 @@ systick-monotonic = "1.0.0" [dev-dependencies.panic-semihosting] features = ["exit"] -version = "0.5.2" +version = "0.6.0" [target.x86_64-unknown-linux-gnu.dev-dependencies] trybuild = "1" diff --git a/book/en/src/SUMMARY.md b/book/en/src/SUMMARY.md index 045036ea..853f3a53 100644 --- a/book/en/src/SUMMARY.md +++ b/book/en/src/SUMMARY.md @@ -29,6 +29,7 @@ - [v0.4.x to v0.5.x](./migration/migration_v4.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)--> diff --git a/book/en/src/by-example/starting_a_project.md b/book/en/src/by-example/starting_a_project.md index c916479a..ccb0083c 100644 --- a/book/en/src/by-example/starting_a_project.md +++ b/book/en/src/by-example/starting_a_project.md @@ -1,6 +1,9 @@ # Starting a new project -A recommendation when starting a RTIC project from scratch is to follow RTIC's [`defmt-app-template`]. +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 diff --git a/book/en/src/internals/targets.md b/book/en/src/internals/targets.md new file mode 100644 index 00000000..04fd5922 --- /dev/null +++ b/book/en/src/internals/targets.md @@ -0,0 +1,71 @@ +# Target Architecture + +While RTIC can currently target all Cortex-m devices there are some key architecure 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/cortex-m-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 implementation is covered in depth by the [Critical Sections][critical_sections] 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 resouces with B. In effect +this creates a virtual priority ceiling, miroring the `BASEPRI` approach described in the +[Critical Sections][critical_Sections] page. 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 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. + +[critical_sections]: https://github.com/rtic-rs/cortex-m-rtic/blob/master/book/en/src/internals/critical-sections.md diff --git a/xtask/Cargo.toml b/xtask/Cargo.toml index 33e6b3ad..f1c468ed 100644 --- a/xtask/Cargo.toml +++ b/xtask/Cargo.toml @@ -5,5 +5,5 @@ edition = "2018" [dependencies] anyhow = "1.0.43" -os_pipe = "0.9.2" +os_pipe = "1.1.2" structopt = "0.3.22" |