From 366fd95b802d1c884b67a268acbef5d21bc71dff Mon Sep 17 00:00:00 2001 From: Robin Jones Date: Wed, 28 Jun 2017 22:54:48 +0100 Subject: [PATCH 1/2] clr managed heap document improvements --- docs/ChibiOS HAL/clr-managed-heap.md | 35 ++++++++++++++-------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/docs/ChibiOS HAL/clr-managed-heap.md b/docs/ChibiOS HAL/clr-managed-heap.md index a08d20f3c2..8216f7ff4a 100644 --- a/docs/ChibiOS HAL/clr-managed-heap.md +++ b/docs/ChibiOS HAL/clr-managed-heap.md @@ -2,38 +2,39 @@ **About this document** -This document describes how the CLR manged heap is defined in a ChibiOS target. +This document describes how the CLR manged heap is defined as a ChibiOS target. -These configurations are located in two linker files: -- [rules.ld](../../targets/CMSIS-OS/ChibiOS/common/rules.ld) (common to all ChibiOS targets **except** the ones with F7 series that have to use [rules_STM32F7xx.ld](../../targets/CMSIS-OS/ChibiOS/common/rules_STM32F7xx.ld) instead) -- the target linker file provided for nanoCLR at the target board folder, e.g. [STM32F091xC.ld](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/nanoCLR/STM32F091xC.ld) +For STM32 based devices: +The configurations are spread between two linker files: +- [rules.ld](../../targets/CMSIS-OS/ChibiOS/common/rules.ld) (which is common to all STM32 based ChibiOS targets **except** the F7 series that use [rules_STM32F7xx.ld](../../targets/CMSIS-OS/ChibiOS/common/rules_STM32F7xx.ld) instead) +- the target linker file provided for the nanoCLR in the target board folder, e.g. [STM32F091xC.ld](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/nanoCLR/STM32F091xC.ld) ## Managed heap location and size -The CLR managed heap can be located at any RAM address space available in the target board. Either internal or external. +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 one is assigned to that same RAM region). +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). -This empowers the target board developer with the maximum possible flexibility regarding here to locate the CLR managed heap and the size of it. +This empowers developers to create new target boards with maximum flexibility of where to locate the CLR managed heap and its size. ### Definition the CLR managed heap location -The location of the CLR managed heap is set in in target linker file provided for nanoCLR at the target board folder, e.g. [STM32F091xC.ld](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/nanoCLR/STM32F091xC.ld) +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) -Near the end of the file, locate this line `REGION_ALIAS("CLR_MANAGED_HEAP_RAM", ram0);`. On the example here the CLR manged heap location is being set at _ram0_ region. The RAM regions are defined on that same file, at the beginning. Please check the ChibiOS documentation for details on how to define the RAM regions. +For exaple 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. ### Definition of the CLR managed heap size -The size of the CLR managed heap is set in CMake file of the target board, e.g. [CMakeLists.txt](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/CMakeLists.txt). -Locate the line containing `--defsym=__clr_managed_heap_size__=0x7000`. On the example here the size of CLR manged heap is being set to 0x7000. +The size of the CLR managed heap is set in the CMake file of the target board, e.g. [CMakeLists.txt](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/CMakeLists.txt). +For example the line will contain something similar to `--defsym=__clr_managed_heap_size__=0x7000`. In the example stated here the size of CLR manged heap is being set to 0x7000. -When defining this size you need to take into account several factors: -- the total available size of the region here it's being placed -- if there are initialized variables assigned to this region how much space of it they are taking -- if the CRT heap is to be located in this region what will be the size left for it and if that is enough +When defining the size you need to take into account several factors: +- the total available size of the region where it's being placed +- if there are initialized variables assigned to this region how much space they are taking +- if the CRT heap is located in this region and the size left for it is enough -The linker will only be able to check if there is enough room for all these and it will complain if there isn't. But it can not check 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 at the build folder after a successful build. Look for the region called `.clr_managed_heap` to see the final address mapping for it. +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. From 4c50b02baf9ead83ae2d142a52f0f6d5657c2999 Mon Sep 17 00:00:00 2001 From: Robin Jones Date: Thu, 29 Jun 2017 00:49:19 +0100 Subject: [PATCH 2/2] spelling mistakes and linker file correction for newer F7 implementation --- docs/ChibiOS HAL/clr-managed-heap.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/ChibiOS HAL/clr-managed-heap.md b/docs/ChibiOS HAL/clr-managed-heap.md index 8216f7ff4a..1f6d9b3534 100644 --- a/docs/ChibiOS HAL/clr-managed-heap.md +++ b/docs/ChibiOS HAL/clr-managed-heap.md @@ -5,9 +5,11 @@ This document describes how the CLR manged heap is defined as a ChibiOS target. For STM32 based devices: -The configurations are spread between two linker files: -- [rules.ld](../../targets/CMSIS-OS/ChibiOS/common/rules.ld) (which is common to all STM32 based ChibiOS targets **except** the F7 series that use [rules_STM32F7xx.ld](../../targets/CMSIS-OS/ChibiOS/common/rules_STM32F7xx.ld) instead) -- the target linker file provided for the nanoCLR in the target board folder, e.g. [STM32F091xC.ld](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/nanoCLR/STM32F091xC.ld) +The configurations are chained by linker files: +- the target linker file provided for the nanoCLR in the target board folder, e.g. [STM32F091xC.ld](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/nanoCLR/STM32F091xC.ld) and from within calls rules.ld **except** the F7 series which calls rules_clr.ld, rules_code.ld, rules_data.ld and rules_stacks.ld directly. +- [rules.ld](../../targets/CMSIS-OS/ChibiOS/common/rules.ld) (which is common to all STM32 based ChibiOS targets and calls the next set of linker files) +- [rules_clr.ld](../../targets/CMSIS-OS/ChibiOS/common/rules_clr.ld), [rules_code.ld](../../targets/CMSIS-OS/ChibiOS/common/rules_code.ld), [rules_data.ld](../../targets/CMSIS-OS/ChibiOS/common/rules_data.ld) and [rules_stacks.ld](../../targets/CMSIS-OS/ChibiOS/common/rules_stacks.ld) + ## Managed heap location and size @@ -23,13 +25,13 @@ This empowers developers to create new target boards with maximum flexibility of 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 exaple 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 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. ### Definition of the CLR managed heap size The size of the CLR managed heap is set in the CMake file of the target board, e.g. [CMakeLists.txt](../../targets/CMSIS-OS/ChibiOS/ST_NUCLEO_F091RC/CMakeLists.txt). -For example the line will contain something similar to `--defsym=__clr_managed_heap_size__=0x7000`. In the example stated here the size of CLR manged heap is being set to 0x7000. +For example the line will contain something similar to `--defsym=__clr_managed_heap_size__=0x7000`. In the example stated here the size of CLR managed heap is being set to 0x7000. When defining the size you need to take into account several factors: - the total available size of the region where it's being placed