Skip to content

Update Rtos.md - DO NOT MERGE (before mbed-os 5.7 release) #340

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Feb 27, 2018
Merged

Update Rtos.md - DO NOT MERGE (before mbed-os 5.7 release) #340

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
94ddf60
Update Rtos.md - DO NOT MERGE (before mbed-os 5.7 release)
Nov 20, 2017
d827afd
Update rtos.md
Nov 21, 2017
99d3973
Closed review comments
Dec 4, 2017
d853226
Copy edit rtos.md
Dec 6, 2017
61809c8
Update config table as per master mbed_rtx_conf.h file
Jan 2, 2018
b52867b
Merge branch 'new_engine' into patch-1
Jan 2, 2018
b817f56
Merge branch 'new_engine' into patch-1
Jan 2, 2018
e827d13
Update rtos.md with suggested changes
Feb 27, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 8 additions & 52 deletions docs/reference/contributing/target/rtos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,75 +1,31 @@
### RTOS

CMSIS/RTX code is imported from [the original CMSIS repository](https://github.com/ARM-software/CMSIS_5/).
CMSIS/RTX code is imported from [the original CMSIS repository](https://github.com/ARM-software/CMSIS_5/) with the help of a Python script in the `mbed-os` repository `mbed-os\tools\importer\importer.py`.

#### Memory considerations

Please note that Arm Mbed OS doesn't use any of the RTX memory models, which are based on static carveouts (memory pools). This approach is not ideal for generic systems, such as Mbed OS, because calculating required numbers of RTOS objects is impossible. To avoid declaring arbitrary large buffers carved out at compile time, limiting the amount of available memory, Mbed OS shifts the responsibility of supplying the backing memory to CMSIS-RTOS2 users.
Please note that Arm Mbed OS doesn't use any of the RTX memory models, which are based on static carveouts (memory pools). This approach is not ideal for platform operating systems, such as Mbed OS, because calculating required numbers of RTOS objects is impossible. To avoid declaring arbitrary large buffers carved out at compile time, limiting the amount of available memory, Mbed OS shifts the responsibility of supplying the backing memory to CMSIS-RTOS2 users.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what the platform operating systems are to be fair.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bulislaw - That change was review comment by @sg- https://github.com/ARMmbed/Handbook/pull/340/files/d827afd63fab6edc4021eec3ddce567217a229d6#diff-d3a387b212d57c83382162e66ce314a0R3

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough.


Developers need to use the Mbed OS RTOS C++ API or supply backing memory for RTX objects to `os*New` calls when using CMSIS-RTOS2 APIs directly. (Please consult CMSIS-RTOS2 documentation for API details.) `mbed_rtos_storage.h` header provides handy wrappers that you can use to secure required memory without exposing the code to RTX implementation details.
Developers need to use the Mbed OS RTOS C++ API or supply backing memory for RTX objects to `os*New` calls when using CMSIS-RTOS2 APIs directly. (Please consult CMSIS-RTOS2 documentation for API details.) The `mbed_rtos_storage.h` header provides wrappers that you can use to secure required memory without exposing the code to RTX implementation details.

#### Configuration

Mbed OS changes to RTX configuration all exist in a single file: `mbed-os/rtos/rtx2/mbed_rtx_conf.h`
Mbed OS changes to RTX configuration all exist in a single file: `mbed-os/rtos/TARGET_CORTEX/mbed_rtx_conf.h`

Option | Value | Description |
-------|-------|-------------|
`OS_STACK_SIZE` | 4K or 2K | For a normal target, the thread stack size is set to 4K; for constrained targets, it's 2K. |
`OS_STACK_SIZE` | 4K | OS Stack size is set as `MBED_CONF_APP_THREAD_STACK_SIZE` which is 4096 as default. |
`OS_TIMER_THREAD_STACK_SIZE` | 768B | Timer thread stack set to 768B that's necessary to support the C++ wrappers (4 instances), but it may require changing to support larger number of active timers. |
`OS_IDLE_THREAD_STACK_SIZE` | 512B | Required to handle Mbed OS wrappers |
`OS_DYNAMIC_MEM_SIZE` | 0 | RTX dynamic memory is disabled. |
`OS_MUTEX_OBJ_MEM` | 1 or 0 | For ARMC, use 1; for other toolchains, it's 0. ARMC uses statically allocated mutexes internally. |
`OS_MUTEX_NUM` | 6 or 0 | For ARMC, use 6; for other toolchains, it's 0. ARMC uses statically allocated mutexes internally. |
`OS_TICK_FREQ` | 1000 | Mbed OS Tickrate requires 1ms system tick. |
`OS_STACK_WATERMARK` | 0 or 1 | Watermarking is enabled if `MBED_STACK_STATS_ENABLED` or `MBED_STACK_STATS_ENABLED` are set. |
`OS_PRIVILEGE_MODE` | 0 or 1 | We set it for 0 if uVisor is enabled, 1 otherwise. |

#### Code structure

Due to differences in how the Mbed OS and CMSIS directory structures look, you can't import the original code directly. Some directory changes are necessary:

CMSIS5 | Mbed OS | Explanation |
-------|---------|-------------|
`CMSIS_5/CMSIS/Core/Include/core_*.h` | `mbed-os/cmsis/` | Core specific code |
`CMSIS_5/CMSIS/Core/Include/tz_context.h` | `mbed-os/cmsis/` | TrustZone code |
`CMSIS_5/CMSIS/Core/Include/cmsis_compiler.h` | `mbed-os/cmsis/` | Toolchain generic code |
`CMSIS_5/CMSIS/Core/Include/cmsis_{armcc,armclang,gcc}.h` | `mbed-os/cmsis/TOOLCHAIN_{ARM,GCC}/` | Toolchain specific code |
`CMSIS_5/CMSIS/RTOS2/Include/cmsis_os2.h` | `mbed-os/rtos/TARGET_CORTEX/rtx5/` | RTX main header |
`CMSIS_5/CMSIS/RTOS2/RTX/Config/` | `mbed-os/rtos/TARGET_CORTEX/rtx5` | RTX configuration files |
`CMSIS_5/CMSIS/RTOS2/RTX/Include1/` | `mbed-os/rtos/TARGET_CORTEX/rtx4` | RTOS1 compatibility layer |
`CMSIS_5/CMSIS/RTOS2/RTX/Include/` | `mbed-os/rtos/TARGET_CORTEX/rtx5` | RTX definitions |
`CMSIS_5/CMSIS/RTOS2/RTX/Source/rtx_*` | `mbed-os/rtos/TARGET_CORTEX/rtx5` | RTX sources |
`CMSIS_5/CMSIS/RTOS2/RTX/Source/svc_user.c` | `mbed-os/rtos/rtx2/TARGET_CORTEX_M/` | RTX SVC user table |
`CMSIS_5/CMSIS/RTOS2/RTX/Source/{ARM,GCC,IAR}/` | `mbed-os/rtos/TARGET_CORTEX/rtx5/TARGET_{M0,M0P,M3,RTOS_M4_M7,M23,M33}/TOOLCHAIN_{ARM,GCC,IAR}` | Toolchain and core specific exception handlers |
Due to differences in the Mbed OS and CMSIS directory structure, you can't import the original code directly. You should use the `importer.py` and configuration file `cmsis_importer.json` to import upstream CMSIS code.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think right now it's mostly down to build system.


#### Modification

Due to different use cases between Mbed OS and CMSIS, we had to make some modifications to the source code. We've tried to upstream our changes to the CMSIS repository, but in cases where they aren't compatible with CMSIS requirements, we are forced to maintain a small set of changes.

##### CMSIS

Filename | Description |
---------|-------------|
`cmsis_compiler.h` | Added IAR missing __ALIGNED attribute for earlier (less than 7.8.4) versions |
`cmain.S` | custom IAR non-RTOS boot sequence for Mbed |

##### RTX

Filename | Description |
---------|-------------|
`cmsis_os2.h` | Doxygen added; added per-thread uVisor context |
`cmsis_os1.h` | Change `osThreadDef` to accept 3 parameters rather than 4 and be not static as expected by Mbed OS |
`core_cm.h` | Doxygen added; included headers changed to match Mbed OS core selection; deferred priority setting of SVCall to uVisor when uVisor is enabled |
`RTX_Config.h` | Doxygen added; Mbed OS RTX config included |
`rtx_evr.c` | CMSIS component definition include removed |
`rtx_evr.h` | Doxygen added |
`rtx_thread.c` | Added per-thread uVisor context; notify uVisor of OS events |
`rtx_kernel.c` | Added per-thread uVisor context; notify uVisor of OS events |
`rtx_lib.h` | Doxygen added; added per-thread uVisor context |
`rtx_os.h` | Doxygen added; added per-thread uVisor context |
`irq_cm4.s` | For all toolchains: added case for Cortex M4 cores without VFP |
`svc_user.c` | Removed as its template file and should not be in our code base |
`rt_OsEventObserver.{c,h}` | Added an interface for uVisor to be notified about certain events from privileged code |
`irq_armv8mbl.S` | IAR toolchain: added file for Cortex M23 core |
`irq_armv8mml.S` | IAR toolchain: added file for Cortex M33 core |

<span class="notes">**Note:** For all toolchains, Mbed OS uses `irq_cm0.s` for both M0 and M0P cores.</span>
Due to different use cases between Mbed OS and CMSIS, we modified the source code. We upstream our changes to the CMSIS repository, but in cases when they aren't compatible with CMSIS requirements, we maintain a small set of changes. We maintain changes as separate commits in `mbed-os`, and SHAs are in the `commit_sha` section of the `cmsis_importer.json` file.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Due to different use cases between Mbed OS and CMSIS, we modified the source code

that's a bit vogue, which source code?

We upstream our changes to the CMSIS repository, but in cases when they aren't compatible with CMSIS requirements, we maintain a small set of changes. We maintain changes as separate commits in mbed-os, and SHAs are in the commit_sha section of the cmsis_importer.json file.

That is a bit confusing. @AnotherButler what do you think?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bulislaw What part do you think is confusing?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe confusing isn't the best word for that, but we repeat ourselves and it makes it feel like we talk about something else (?) we maintain a small set of changes. We maintain changes if I'm saying gibberish please ignore :)