From f52b5fd1c4410e972ec642e331a86850c9a75ef2 Mon Sep 17 00:00:00 2001 From: Nathan Date: Fri, 16 Dec 2022 11:38:02 -0600 Subject: [PATCH 1/9] Add documentation for different targets --- book/en/src/by-example/starting_a_project.md | 5 +- book/en/src/internals/targets.md | 59 ++++++++++++++++++++ 2 files changed, 63 insertions(+), 1 deletion(-) create mode 100644 book/en/src/internals/targets.md diff --git a/book/en/src/by-example/starting_a_project.md b/book/en/src/by-example/starting_a_project.md index c916479aa8..c4f49b6ba1 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 on an ARMv7-M or ARMv8-M-main MCU is to +follow RTIC's [`defmt-app-template`]. For ARMv6-M or ARMv8-M-base, check out Section 4.? of +this book for more information on hardware and implementation differences to be aware of before +starting with RTIC. [`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 0000000000..0104cdba8c --- /dev/null +++ b/book/en/src/internals/targets.md @@ -0,0 +1,59 @@ +# Target Architecture + +While RTIC can currently target all Cortex-m devices there are some key architecure differences that +users should be aware. Namely the absence of hardware priority ceiling (BASEPRI) support in the +ARMv6-M and ARMv8-M-base architectures requires a few tweaks from RTIC to deliver the same +features. These differences result in two flavors of critical sections: priority ceiling, and source +masking. 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-M23 | ARMv8-M-base | | ઙ | +| Cortex-M33 | ARMv8-M-main | ઙ | | +| Cortex-M7 | ARMv7-M | ઙ | | + +## Priority Ceiling + +This implementation is covered in depth by Chapter 4.5 of this book. + +## Source Masking + +Since there is no hardware support for a priority ceiling, RTIC must instead rely on the Nested +Vectored Interrupt Controller (NVIC) present in the core architecture. 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 all other tasks which share +the resource using the NVIC. In effect this raisis the virtual priority ceiling. 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 it's priority is +greater. This is because the NVIC is preventing it from starting due to task A's source mask 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. From c8d60d2910137381c9e6101b92976d47e256701e Mon Sep 17 00:00:00 2001 From: n8tlarsen <96437952+n8tlarsen@users.noreply.github.com> Date: Mon, 19 Dec 2022 17:45:53 -0600 Subject: [PATCH 2/9] Improve basepri explanation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Tjäder --- book/en/src/internals/targets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/en/src/internals/targets.md b/book/en/src/internals/targets.md index 0104cdba8c..65c0712534 100644 --- a/book/en/src/internals/targets.md +++ b/book/en/src/internals/targets.md @@ -1,7 +1,7 @@ # Target Architecture While RTIC can currently target all Cortex-m devices there are some key architecure differences that -users should be aware. Namely the absence of hardware priority ceiling (BASEPRI) support in the +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 requires a few tweaks from RTIC to deliver the same features. These differences result in two flavors of critical sections: priority ceiling, and source masking. Table 1 below shows a list of Cortex-m processors and which type of critical section they From 60132495d96f99af525df0122989f08b5206e854 Mon Sep 17 00:00:00 2001 From: n8tlarsen <96437952+n8tlarsen@users.noreply.github.com> Date: Mon, 19 Dec 2022 17:48:52 -0600 Subject: [PATCH 3/9] Expand lock explanation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Tjäder --- book/en/src/internals/targets.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/book/en/src/internals/targets.md b/book/en/src/internals/targets.md index 65c0712534..bdfb24bb2d 100644 --- a/book/en/src/internals/targets.md +++ b/book/en/src/internals/targets.md @@ -2,10 +2,13 @@ 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 requires a few tweaks from RTIC to deliver the same -features. These differences result in two flavors of critical sections: priority ceiling, and source -masking. Table 1 below shows a list of Cortex-m processors and which type of critical section they -employ. +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* From 70ebcc409ff4e34764337a978882a25f34484c4f Mon Sep 17 00:00:00 2001 From: n8tlarsen <96437952+n8tlarsen@users.noreply.github.com> Date: Mon, 19 Dec 2022 18:16:25 -0600 Subject: [PATCH 4/9] Clarify BASEPRI and NVIC interaction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Tjäder --- book/en/src/internals/targets.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/book/en/src/internals/targets.md b/book/en/src/internals/targets.md index bdfb24bb2d..606191d20f 100644 --- a/book/en/src/internals/targets.md +++ b/book/en/src/internals/targets.md @@ -28,8 +28,10 @@ This implementation is covered in depth by Chapter 4.5 of this book. ## Source Masking -Since there is no hardware support for a priority ceiling, RTIC must instead rely on the Nested -Vectored Interrupt Controller (NVIC) present in the core architecture. Consider Figure 1 below, +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* From c688b601f1b447d51398ae3caac8ed5155cdbeb1 Mon Sep 17 00:00:00 2001 From: n8tlarsen <96437952+n8tlarsen@users.noreply.github.com> Date: Mon, 19 Dec 2022 18:17:06 -0600 Subject: [PATCH 5/9] typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Tjäder --- book/en/src/internals/targets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/en/src/internals/targets.md b/book/en/src/internals/targets.md index 606191d20f..4972e5fcb3 100644 --- a/book/en/src/internals/targets.md +++ b/book/en/src/internals/targets.md @@ -51,7 +51,7 @@ showing two tasks A and B where A has higher priority but shares a resource with ``` At time *t1*, task B locks the shared resource by selectively disabling all other tasks which share -the resource using the NVIC. In effect this raisis the virtual priority ceiling. Task A is one such +the resource using the NVIC. In effect this raises the virtual priority ceiling. 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 it's priority is greater. This is because the NVIC is preventing it from starting due to task A's source mask being From dd1fb68f425d4bc4712b6c6bfe8313d6270017ff Mon Sep 17 00:00:00 2001 From: n8tlarsen <96437952+n8tlarsen@users.noreply.github.com> Date: Mon, 19 Dec 2022 18:18:04 -0600 Subject: [PATCH 6/9] Possessive its MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Tjäder --- book/en/src/internals/targets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/en/src/internals/targets.md b/book/en/src/internals/targets.md index 4972e5fcb3..da55937157 100644 --- a/book/en/src/internals/targets.md +++ b/book/en/src/internals/targets.md @@ -53,7 +53,7 @@ showing two tasks A and B where A has higher priority but shares a resource with At time *t1*, task B locks the shared resource by selectively disabling all other tasks which share the resource using the NVIC. In effect this raises the virtual priority ceiling. 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 it's priority is +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's source mask 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 From 27d41c1a3867c4a509e8c153bfc2e013f280ce46 Mon Sep 17 00:00:00 2001 From: n8tlarsen <96437952+n8tlarsen@users.noreply.github.com> Date: Wed, 21 Dec 2022 17:02:11 -0600 Subject: [PATCH 7/9] Revert recommended starting template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Henrik Tjäder --- book/en/src/by-example/starting_a_project.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/en/src/by-example/starting_a_project.md b/book/en/src/by-example/starting_a_project.md index c4f49b6ba1..ccb0083c07 100644 --- a/book/en/src/by-example/starting_a_project.md +++ b/book/en/src/by-example/starting_a_project.md @@ -1,9 +1,9 @@ # Starting a new project -A recommendation when starting a RTIC project from scratch on an ARMv7-M or ARMv8-M-main MCU is to -follow RTIC's [`defmt-app-template`]. For ARMv6-M or ARMv8-M-base, check out Section 4.? of -this book for more information on hardware and implementation differences to be aware of before -starting with RTIC. +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 From 80b81ef122e68744744df9e866fec3263a0d7e11 Mon Sep 17 00:00:00 2001 From: Nathan Date: Thu, 29 Dec 2022 10:20:46 -0600 Subject: [PATCH 8/9] Update example with SRP priority ceiling --- book/en/src/internals/targets.md | 41 +++++++++++++++++++------------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/book/en/src/internals/targets.md b/book/en/src/internals/targets.md index da55937157..dfb68deaef 100644 --- a/book/en/src/internals/targets.md +++ b/book/en/src/internals/targets.md @@ -1,12 +1,17 @@ # 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]. +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. +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. @@ -18,21 +23,20 @@ Table 1 below shows a list of Cortex-m processors and which type of critical sec | 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 | ઙ | | -| Cortex-M7 | ARMv7-M | ઙ | | ## Priority Ceiling -This implementation is covered in depth by Chapter 4.5 of this book. +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. +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* @@ -50,15 +54,18 @@ showing two tasks A and B where A has higher priority but shares a resource with t1 t2 t3 t4 ``` -At time *t1*, task B locks the shared resource by selectively disabling all other tasks which share -the resource using the NVIC. In effect this raises the virtual priority ceiling. 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's source mask 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. +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 From 9c68b876f17b72cca68491bd31b47481e5f90f2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henrik=20Tj=C3=A4der?= Date: Wed, 4 Jan 2023 21:20:24 +0100 Subject: [PATCH 9/9] Enable the targets chapter --- book/en/src/SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/en/src/SUMMARY.md b/book/en/src/SUMMARY.md index 045036eab5..853f3a5319 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)