Skip to content

Commit 80b81ef

Browse files
committed
Update example with SRP priority ceiling
1 parent 27d41c1 commit 80b81ef

File tree

1 file changed

+24
-17
lines changed

1 file changed

+24
-17
lines changed

book/en/src/internals/targets.md

Lines changed: 24 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
11
# Target Architecture
22

33
While RTIC can currently target all Cortex-m devices there are some key architecure differences that
4-
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
5-
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].
4+
users should be aware of. Namely the absence of Base Priority Mask Register (`BASEPRI`) which lends
5+
itself exceptionally well to the hardware priority ceiling support used in RTIC, in the ARMv6-M and
6+
ARMv8-M-base architectures, which forces RTIC to use source masking instead. For each implementation
7+
of lock and a detailed commentary of pros and cons, see the implementation of
8+
[lock in src/export.rs][src_export].
69

710
[src_export]: https://github.com/rtic-rs/cortex-m-rtic/blob/master/src/export.rs
811

9-
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.
12+
These differences influence how critical sections are realized, but functionality should be the same
13+
except that ARMv6-M/ARMv8-M-base cannot have tasks with shared resources bound to exception
14+
handlers, as these cannot be masked in hardware.
1015

1116
Table 1 below shows a list of Cortex-m processors and which type of critical section they employ.
1217

@@ -18,21 +23,20 @@ Table 1 below shows a list of Cortex-m processors and which type of critical sec
1823
| Cortex-M0+ | ARMv6-M | | &#2713 |
1924
| Cortex-M3 | ARMv7-M | &#2713 | |
2025
| Cortex-M4 | ARMv7-M | &#2713 | |
26+
| Cortex-M7 | ARMv7-M | &#2713 | |
2127
| Cortex-M23 | ARMv8-M-base | | &#2713 |
2228
| Cortex-M33 | ARMv8-M-main | &#2713 | |
23-
| Cortex-M7 | ARMv7-M | &#2713 | |
2429

2530
## Priority Ceiling
2631

27-
This implementation is covered in depth by Chapter 4.5 of this book.
32+
This implementation is covered in depth by the [Critical Sections][critical_sections] page of this book.
2833

2934
## Source Masking
3035

3136
Without a `BASEPRI` register which allows for directly setting a priority ceiling in the Nested
3237
Vectored Interrupt Controller (NVIC), RTIC must instead rely on disabling (masking) interrupts.
33-
34-
Consider Figure 1 below,
35-
showing two tasks A and B where A has higher priority but shares a resource with B.
38+
Consider Figure 1 below, showing two tasks A and B where A has higher priority but shares a resource
39+
with B.
3640

3741
#### *Figure 1: Shared Resources and Source Masking*
3842

@@ -50,15 +54,18 @@ showing two tasks A and B where A has higher priority but shares a resource with
5054
t1 t2 t3 t4
5155
```
5256

53-
At time *t1*, task B locks the shared resource by selectively disabling all other tasks which share
54-
the resource using the NVIC. In effect this raises the virtual priority ceiling. Task A is one such
55-
task that shares resources with task B. At time *t2*, task A is either spawned by task B or becomes
56-
pending through an interrupt condition, but does not yet preempt task B even though its priority is
57-
greater. This is because the NVIC is preventing it from starting due to task A's source mask being
58-
disabled. At time *t3*, task B releases the lock by re-enabling the tasks in the NVIC. Because
59-
task A was pending and has a higher priority than task B, it immediately preempts task B and is
60-
free to use the shared resource without risk of data race conditions. At time *t4*, task A completes
61-
and returns the execution context to B.
57+
At time *t1*, task B locks the shared resource by selectively disabling (using the NVIC) all other
58+
tasks which have a priority equal to or less than any task which shares resouces with B. In effect
59+
this creates a virtual priority ceiling, miroring the `BASEPRI` approach described in the
60+
[Critical Sections][critical_Sections] page. Task A is one such task that shares resources with
61+
task B. At time *t2*, task A is either spawned by task B or becomes pending through an interrupt
62+
condition, but does not yet preempt task B even though its priority is greater. This is because the
63+
NVIC is preventing it from starting due to task A being being disabled. At time *t3*, task B
64+
releases the lock by re-enabling the tasks in the NVIC. Because task A was pending and has a higher
65+
priority than task B, it immediately preempts task B and is free to use the shared resource without
66+
risk of data race conditions. At time *t4*, task A completes and returns the execution context to B.
6267

6368
Since source masking relies on use of the NVIC, core exception sources such as HardFault, SVCall,
6469
PendSV, and SysTick cannot share data with other tasks.
70+
71+
[critical_sections]: https://github.com/rtic-rs/cortex-m-rtic/blob/master/book/en/src/internals/critical-sections.md

0 commit comments

Comments
 (0)