Skip to content
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

clr managed heap document improvements #369

Merged
merged 2 commits into from
Jun 28, 2017
Merged

clr managed heap document improvements #369

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
366fd95
clr managed heap document improvements
networkfusion Jun 28, 2017
4c50b02
spelling mistakes and linker file correction for newer F7 implementation
networkfusion Jun 28, 2017
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
35 changes: 18 additions & 17 deletions docs/ChibiOS HAL/clr-managed-heap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Copy link
Member Author

Choose a reason for hiding this comment

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

Actually I don't think this is true any more, the F7 actually defines the differences within its own ld.

Copy link
Member

Choose a reason for hiding this comment

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

I agree!

Copy link
Member

Choose a reason for hiding this comment

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

I believe that you are correct. Care to update the bit above so this can be merged? 😉

Copy link
Member

Choose a reason for hiding this comment

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

Who ever made the change, should check it's spellchecker. It has some bugs, line 26 and 32 have some new words I didn't know before or and most likely the words exaple (line 26) and manged (line 32) are waiting to be corrected.

Copy link
Member Author

Choose a reason for hiding this comment

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

@piwi1263 done (I didn't have a spell checker installed, I have now :-p) typing too quickly for my own good!

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