Add CMSIS-RTOS documentation #160

bulislaw · 2017-05-10T09:40:59Z

Document CMSIS-RTOS and RTX usage in mbed OS.

Should be merged after ARMmbed/mbed-os#4294

@AnotherButler could you please have a look

AnotherButler

@bulislaw I've left four queries for you. Would you like me to make my grammar edits directly to your PR, or would you like me to leave them in comment form for you to make?

AnotherButler · 2017-05-11T22:40:43Z

docs/advanced/cmsis-rtos.md

@@ -0,0 +1,77 @@
+# CMSIS & RTX
+
+CMSIS/RTX code is imported from the original CMSIS repository which can be found: https://github.com/ARM-software/CMSIS_5/


Query: Who or what does the importing? Please clarify.

CMSIS/RTX is a separate repository (also owned by ARM). We take code from this external repo and import it in mbed OS codebase. Every now and again we will import new version of the code.

AnotherButler · 2017-05-11T22:48:49Z

docs/advanced/cmsis-rtos.md

+
+## Configuration
+
+mbed OS changes to RTX configuration are all maintained in a single file: `mbed-os/rtos/rtx2/mbed_rtx_conf.h`


Query: Who or what maintains these changes? Please clarify.

We do. The point is not to change configuration options in different places of mbed OS as we used to do it, but have one central file where all of the default changes are made.

AnotherButler · 2017-05-11T23:05:46Z

docs/advanced/cmsis-rtos.md

+
+#### Other
+
+* irq_cm0.s is used for both M0 and M0P cores in mbed OS for all toolchains


Query: Who or what uses irq_cm0.s? Please clarify.

mbed OS is using these files for M0/M0P boards. The point i wanted to make is that there's one original file, with name suggesting it's for M0 only, but in reality we use it for both type of cores.

AnotherButler · 2017-05-11T23:20:40Z

docs/advanced/cmsis-rtos.md

+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 it's template file and should not be in our code base |
+rt_OsEventObserver.{c,h} | Added an interface for uVisor to get notified about certain events from privileged code |


Query: Is the Description column a description of what the filename does? If so, could you please reword the Description column to be in present tense [such as "Adds Doxygen" instead of "Doxygen added"]? If not, could you please clarify?

It's part of the 'Changes' section, 'description' column documents what changes we (mbed OS) made to the original code imported from external repository.

bulislaw

Thanks for that! Sounds better now :)

bulislaw · 2017-05-12T15:39:45Z

docs/advanced/cmsis-rtos.md


 ## Memory considerations

-Please note that 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 system like mbed OS as calculating required numbers of RTOS objects is impossible. To avoid declaring arbitrary large buffers, carved out on compile time, limiting amount of available memory, mbed OS shifts the responsibility of supplying the backing memory to CMSIS-RTOS2 users.
+Please note that 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 system, such as mbed O,S because calculating required numbers of RTOS objects is impossible. To avoid declaring arbitrary large buffers, carved out on compile time, limiting amount of available memory, mbed OS shifts the responsibility of supplying the backing memory to CMSIS-RTOS2 users.


O,S because

bulislaw · 2017-05-12T15:41:14Z

docs/advanced/cmsis-rtos.md


-Therefore developers will need to use 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 can be used to secure required memory without exposing the code to RTX implementation details.
+Therefore 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.


directly. (Please consult CMSIS-RTOS2 documentation for API details.) I think the dot should be on the other side of the bracketed bit, as it refers to the CMSIS-RTOS2 rather than mbed_rtos_storage.h

bulislaw · 2017-05-12T15:43:28Z

docs/advanced/cmsis-rtos.md


 ## Code structure

-Due to differences in how mbed OS and CMSIS directory structures look like, we can't import the original code directly, some directory changes are necessary:
+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:


That's not a big deal, but it's not about the users, it's about the maintainers (us). This import is done, and may be needed to be done in the future to update CMSIS (external component) version.

AnotherButler · 2017-05-17T14:15:00Z

docs/advanced/cmsis-rtos.md

@@ -51,6 +51,7 @@ Due to different use cases between mbed OS and CMSIS, we had to make some modifi
 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 |


Please change "non-rtos" to "non-RTOS" for consistent capitalization.

theotherjimmy · 2017-05-18T19:02:06Z

docs/advanced/cmsis-rtos.md

+
+## Memory considerations
+
+Please note that 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 system, such as mbed O,S because calculating required numbers of RTOS objects is impossible. To avoid declaring arbitrary large buffers, carved out on compile time, limiting amount of available memory, mbed OS shifts the responsibility of supplying the backing memory to CMSIS-RTOS2 users.


generic system => generic systems or a generic system
mbed O,S => mbed OS,
carved out on compile time => carved out at compile time
limiting amount of available memory => limiting the amount of available memory

theotherjimmy · 2017-05-18T19:16:04Z

docs/advanced/cmsis-rtos.md

+
+Please note that 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 system, such as mbed O,S because calculating required numbers of RTOS objects is impossible. To avoid declaring arbitrary large buffers, carved out on compile time, limiting amount of available memory, mbed OS shifts the responsibility of supplying the backing memory to CMSIS-RTOS2 users.
+
+Therefore 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.


My preference is to avoid starting a paragraph with "Therefore"

theotherjimmy · 2017-05-18T19:19:19Z

docs/advanced/cmsis-rtos.md

+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 |


Wrong number of ` should be one.

theotherjimmy · 2017-05-18T19:20:18Z

docs/advanced/cmsis-rtos.md

+`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 |
+
+#### Other


Should be on the same level as RTX: 3*#

AnotherButler · 2017-05-24T16:24:23Z

@bulislaw Once y'all resolve the comments from @theotherjimmy, could you please add the missing "t" in "documentation" in the subject line? If you'd like me to, I can also make that change for you. Just let me know. Thanks so much.

Copy edit, mostly for active voice, consistent tense and consistent code format.

bulislaw · 2017-05-25T10:03:28Z

Should be fixed now.

AnotherButler · 2017-06-12T15:24:15Z

@bulislaw Is it OK if I move this to the 5.5 docs branch, which I just created?

AnotherButler · 2017-06-13T19:33:33Z

@theotherjimmy Is this OK to merge?

theotherjimmy · 2017-06-13T19:38:02Z

yes

bulislaw mentioned this pull request May 10, 2017

Update CMSIS-Core and RTX to version 5 ARMmbed/mbed-os#4294

Merged

6 tasks

AnotherButler reviewed May 11, 2017

View reviewed changes

bulislaw commented May 12, 2017

View reviewed changes

bulislaw mentioned this pull request May 17, 2017

Revert partially "Remove Cortex A support from CMSIS/RTOS" ARMmbed/mbed-os#4334

Merged

AnotherButler reviewed May 17, 2017

View reviewed changes

0xc0170 force-pushed the feature_cmsis5 branch from ecddc03 to e8acc2b Compare May 17, 2017 14:33

theotherjimmy mentioned this pull request May 18, 2017

Update CMSIS-Core and RTX to version 5 ARMmbed/mbed-os#4346

Closed

6 tasks

theotherjimmy reviewed May 18, 2017

View reviewed changes

bulislaw and others added 4 commits May 25, 2017 10:59

Add CMSIS-RTOS documentation

5e755c6

Update cmsis-rtos.md

865eee8

Copy edit, mostly for active voice, consistent tense and consistent code format.

cmsis-rtos: add cmain.S IAR seq file to cmsis

e3ea77f

Fix issues pointed during the review

d18ca3a

bulislaw force-pushed the feature_cmsis5 branch from e8acc2b to d18ca3a Compare May 25, 2017 10:00

bulislaw changed the title ~~Add CMSIS-RTOS documenation~~ Add CMSIS-RTOS documentation May 25, 2017

AnotherButler added the wait to merge label Jun 2, 2017

AnotherButler changed the base branch from 5.4 to 5.5 June 12, 2017 15:18

AnotherButler merged commit 82eb986 into ARMmbed:5.5 Jun 13, 2017

AnotherButler removed the wait to merge label Jun 13, 2017

		@@ -0,0 +1,77 @@
		# CMSIS & RTX

		CMSIS/RTX code is imported from the original CMSIS repository which can be found: https://github.com/ARM-software/CMSIS_5/


		## Configuration

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


		#### Other

		* irq_cm0.s is used for both M0 and M0P cores in mbed OS for all toolchains


		Therefore developers will need to use 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 can be used to secure required memory without exposing the code to RTX implementation details.
		Therefore 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.


		## Memory considerations

		Please note that 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 system, such as mbed O,S because calculating required numbers of RTOS objects is impossible. To avoid declaring arbitrary large buffers, carved out on compile time, limiting amount of available memory, mbed OS shifts the responsibility of supplying the backing memory to CMSIS-RTOS2 users.

Add CMSIS-RTOS documentation #160

Add CMSIS-RTOS documentation #160

Uh oh!

Conversation

bulislaw commented May 10, 2017

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bulislaw left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler commented May 24, 2017

Uh oh!

bulislaw commented May 25, 2017

Uh oh!

AnotherButler commented Jun 12, 2017

Uh oh!

AnotherButler commented Jun 13, 2017

Uh oh!

theotherjimmy commented Jun 13, 2017

Uh oh!

Uh oh!