From 4d4e86d6aaf772553bb906b1d18f0b5c8646058d Mon Sep 17 00:00:00 2001 From: Robin Jones Date: Mon, 3 Jul 2017 11:29:04 +0100 Subject: [PATCH] updated documents --- docs/ChibiOS HAL/clr-managed-heap.md | 8 ++++---- docs/architecture/thread-execution.md | 14 +++++++------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/ChibiOS HAL/clr-managed-heap.md b/docs/ChibiOS HAL/clr-managed-heap.md index 1f6d9b3534..23a3e311a7 100644 --- a/docs/ChibiOS HAL/clr-managed-heap.md +++ b/docs/ChibiOS HAL/clr-managed-heap.md @@ -16,16 +16,16 @@ The configurations are chained by linker files: The CLR managed heap can be located on the target board at any RAM address where space available. Either internal or external. -It will be placed (considering the RAM region defined) after the region containing the initialized variables (if any is assigned to that RAM region) and before the CRT heap (if this is assigned to the same RAM region). +It will be placed (considering the RAM region defined) after the region containing the initialized variables (if any are assigned to that RAM region) and before the CRT heap (if it is assigned to the same RAM region). -This empowers developers to create new target boards with maximum flexibility of where to locate the CLR managed heap and its size. +This empowers developers to create new target boards with maximum flexibility of where to locate the CLR managed heap and its respective size. ### Definition the CLR managed heap location The location of the CLR managed heap is set in in target linker file provided for nanoCLR in the target boards folder, e.g. [STM32F091xC.ld](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/nanoCLR/STM32F091xC.ld) -For example the line (usually toward the end of the file) will contain something similar to `REGION_ALIAS("CLR_MANAGED_HEAP_RAM", ram0);`. The example stated here defines CLR manged heap location as being set in the _ram0_ region. The RAM regions are defined on that same file, at the beginning. For further information, please check the ChibiOS documentation for details on how to define further RAM regions. +For example the line (usually toward the end of the file) will contain something similar to `REGION_ALIAS("CLR_MANAGED_HEAP_RAM", ram0);`. The example stated here defines CLR manged heap location as being set in the _ram0_ region. The RAM regions and respective sizes are defined in the same file. For further information, please check the ChibiOS documentation for details on how to define further RAM regions. ### Definition of the CLR managed heap size @@ -39,4 +39,4 @@ When defining the size you need to take into account several factors: - if the CRT heap is located in this region and the size left for it is enough The linker is only able to determine whether there is enough room for all of these factors and it will only complain if there isn't. However it can not determine if the CRT heap is large enough for the running requirements. That is up to the target board developer. -For a detailed overview on the final memory map you may want to check the _nanoCLR.map_ that will be located in the build folder after a successful build. Look for the region called `.clr_managed_heap` to see the final address mapping for it. +For a detailed overview on the final memory map you may want to check the _nanoCLR.map_ that will be located in the build folder after a successful build. Look for the region called `.clr_managed_heap` to see the final address mapping for it. \ No newline at end of file diff --git a/docs/architecture/thread-execution.md b/docs/architecture/thread-execution.md index a60122c290..7fb2e9fecb 100644 --- a/docs/architecture/thread-execution.md +++ b/docs/architecture/thread-execution.md @@ -2,21 +2,21 @@ **About this document** -This document describes how the execution work on **nanoFramework** CLR. +This document describes how thread execution works with the **nanoFramework** CLR. ## Introduction to Threads -Oversimplifying it a **nanoFramework** thread is (in what concerns the execution) basically a stream of IL instructions that are chewed by the interpreter making things happen. +Oversimplifying it a **nanoFramework** thread is (in terms of execution) basically a stream of IL instructions that are translated by the interpreter making things happen. This execution occurs in a cooperative fashion, meaning that a thread is allowed to run for a certain amount of time, after that it stops and the execution is passed to the next thread that meets the required conditions to run. ## Thread execution -The **nanoFramework** CLR and interpreter run on a RTOS thread. When the RTOS works on a [cooperative](https://en.wikipedia.org/wiki/Computer_multitasking#Cooperative_multitasking) fashion (opposed to a [preemptive](https://en.wikipedia.org/wiki/Computer_multitasking#Preemptive_multitasking) fashion) the thread is expected to relinquish control to the RTOS so that the context switching can occur and the next RTOS thread is given the opportunity to run. +The **nanoFramework** CLR and interpreter run on a RTOS thread. When the RTOS works in a [cooperative](https://en.wikipedia.org/wiki/Computer_multitasking#Cooperative_multitasking) fashion (opposed to a [preemptive](https://en.wikipedia.org/wiki/Computer_multitasking#Preemptive_multitasking) fashion) the thread is expected to relinquish control to the RTOS so that context switching can occur and the next RTOS thread is given the opportunity to run. This context switching in **nanoFramework** is expected to occur after each time slot that a **nanoFramework** thread is allowed to run. -It's up to the target board developer to provide the correct way to perform that execution control relinquish according to the RTOS beneath. -This may not be required at all. For example when the RTOS works, by default, on a preemptive fashion. In this case the thread execution occurs in a round and robin among the various RTOS threads. +It's up to the target board developer to provide the correct way to relinquish the control of the threads execution according to the RTOS running beneath. +This may not be required by all RTOS's. For example when by default the RTOS works in a preemptive fashion, the thread execution occurs in a round robin fashion among the various RTOS threads. -The declaration of this _execution control relinquish_ is declared as `NANOCLR_RELINQUISHEXECUTIONCONTROL` in [nanoHAL_v2.h](../../src/HAL/Include/nanoHAL_v2.h). The actual implementation has to be provided at target level in the `targetHAL.h` header. -For the current version - that relies on ChibiOS (a CMSIS compliant RTOS) - this is a simple call to `osDelay(1)` which allows the kernel to run all the other threads with the same (or higher) priority. +_execution control relinquish_ is declared as `NANOCLR_RELINQUISHEXECUTIONCONTROL` in [nanoHAL_v2.h](../../src/HAL/Include/nanoHAL_v2.h). The actual implementation has to be provided at the target board level in the `targetHAL.h` header file. +For the current version of **nanoFramework** - which is using ChibiOS (a CMSIS compliant RTOS) - a simple call to `osDelay(1)` is sufficient and allows the kernel to run all the other threads with the same (or higher) priority.