Skip to content

Commit 8ba28c0

Browse files
author
Deepika
committed
Add RAM memory model update document
1 parent ec86ee1 commit 8ba28c0

File tree

1 file changed

+105
-0
lines changed

1 file changed

+105
-0
lines changed

‎docs/design-documents/platform/memory-model/ram_memory_model.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# RAM memory model update - Mbed OS
2+
3+
# Table of contents
4+
5+
1. [RAM memory model update - Mbed OS](#mbed-os-ram-memory-model).
6+
1. [Table of contents](#table-of-contents).
7+
1. [Revision history](#revision-history).
8+
1. [Introduction](#introduction).
9+
1. [Current RAM memory model](#current-ram-memory-model).
10+
1. [Proposed RAM memory model](#proposed-ram-memory-model).
11+
1. [Phases](#phases).
12+
1. Detailed Design (#detailed-design).
13+
1. [Tools and configuration changes](#tools-and-configuration-changes).
14+
15+
### Revision history
16+
17+
1.0 - A brief description of this version. For example, Initial revision - Author name - Date.
18+
**NOTE: You may also specify the Mbed OS version this revision of design document applies to.**
19+
1.1 - Added new section - Author name - Date.
20+
21+
# Introduction
22+
23+
### Current RAM memory model
24+
25+
Single memory space is shared between stack and heap memory, start address is fixed but the size of both regions varies based on application and usage runtime.
26+
Heap starts at the first address after the end of ZI growing up into higher memory address and stack starts at the last memory address of RAM growing downwared into lower addresses.
27+
28+
+----------------------+ Stack Start (Last address of RAM)
29+
| ISR stack |
30+
| Main Stack(No RTOS) |
31+
| | |
32+
| V |
33+
+----------------------+
34+
| ^ |
35+
| | |
36+
| Heap |
37+
+----------------------+ HEAP Start
38+
| ZI |
39+
|(Idle, Timer and Main |
40+
| stack is in ZI for |
41+
| RTOS) |
42+
+----------------------+
43+
| |
44+
+----------------------+ First address of RAM
45+
46+
#### Drawbacks:
47+
1. Collisions between stack and heap are hard to detect and result in hardfault.
48+
1. Cannot check stack limit - In case of new ARM architecture stack limit registers are available to verify stack boundaries, but this feature cannot be used with dynamic stack size.
49+
1. Stack size unification cannot be achieved across various targets.
50+
1. GCC ARM: Memory allocator request memory at 4K boundary end of HEAP memory should be 4K aligned. Placing ISR stack (1K) after HEAP memory in case of RTOS, results in loss of 3K RAM memory
51+
1. Memory alloctors do not support HEAP split into multiple banks, hence with single region memory model HEAP is used only till end of first bank.
52+
53+
### Proposed RAM memory model
54+
55+
2-region memory model for heap and stack. Defined boundaries for ISR stack memory. Heap memory can be dynamic (starts at end of ZI and ends at last RAM address) or with fix boundaries in separate RAM bank.
56+
57+
+----------------------+ Heap Ends (Last address of RAM)
58+
| ^ |
59+
| | |
60+
| Heap |
61+
+----------------------+ HEAP Start
62+
| ZI |
63+
|(Idle, Timer and Main |
64+
| stack is in ZI for |
65+
| RTOS) |
66+
+----------------------+Stack Ends
67+
| ISR stack |
68+
| Main Stack(No RTOS) |
69+
| | |
70+
| V |
71+
+----------------------+Stack Start
72+
| |
73+
+----------------------+ First address of RAM
74+
75+
#### Drawbacks:
76+
1. ISR Stack is not dynamic - This drawback is mainly for bare metal implementation (RTOS-less) where ISR and Main stack is same. With this limitation application writer should know if stack or heap will be usued more and tweaks the values accordingly.
77+
78+
# Phases:
79+
This feature will be implemented in different phases as follow:
80+
81+
Phase 1 (5.12 Release):
82+
1. Adopt 2-region memory model for Stack and Heap memory.
83+
1. Unify the stack size accross all targets (RTOS: ISR stack - 1K Main thread Stack - 4K; Bare Metal(No RTOS) ISR/Main Stack - 4K)
84+
85+
Phase 2:
86+
1. Heap memory to be dynamic and starts at the end of ZI growing up till end of RAM memory (In case of single RAM bank)
87+
Heap memory to be dynamic and assigned partial or full RAM bank in case of multiple RAM banks, based on calculation of other RAM regions.
88+
1. ISR Stack to be placed after vectors or before ZI memory section.
89+
90+
Note: Heap split support across multiple RAM banks, can also be achieved post this change.
91+
92+
# Detailed Design
93+
1. Update tools to set define `MBED_BOOT_STACK_SIZE` from target config option `target.boot-stack-size`
94+
1. Linker Scripts - Update linker scripts for ARM, IAR and GCC toolchain to use MBED_BOOT_STACK_SIZE define for standardizing size of ISR stack.
95+
1. Update __user_setup_stackheap() implementation to adopt 2-region RAM memory model.
96+
__user_setup_stackheap() works with systems where the application starts with a value of sp (r13) that is already correct. To make use of sp(stack base), implement __user_setup_stackheap() to set up r0 (heap base), r2 (heap limit), and r3 (stack limit) (for a two-region model) and return.
97+
Reference http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.kui0099a/armlib_cjagaaha.htm http://www.keil.com/support/man/docs/armlib/armlib_chr1359122863069.htm
98+
1. Modify _sbrk() implementation for GCC to use 2-region memory model
99+
100+
# Tools and configuration changes
101+
102+
1. Target config option "target.boot-stack-size" which is passed to the linker as the define "MBED_BOOT_STACK_SIZE" so the linker can adjust the stack accordingly.
103+
Boot stack size - the size of ISR and main stack will be 4K as default in targets.json for bare metal (non-RTOS) builds.
104+
Boot stack size - the size of ISR stack will be over-written as 1K in `rtos/mbed_lib.json` for RTOS builds.
105+

0 commit comments

Comments
 (0)