From 223136a15fc7f3c6bf528b4cadd7b62f0ed110d0 Mon Sep 17 00:00:00 2001 From: Martine Lenders Date: Fri, 6 Dec 2024 13:02:28 +0100 Subject: [PATCH] doc/static-vs-dynamic-memory: move to dev-best-practices --- doc/doxygen/riot.doxyfile | 1 - doc/doxygen/src/dev-best-practices.md | 29 ++++++++++++++++++++- doc/doxygen/src/static-vs-dynamic-memory.md | 29 --------------------- 3 files changed, 28 insertions(+), 31 deletions(-) delete mode 100644 doc/doxygen/src/static-vs-dynamic-memory.md diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile index b6febd4ba04c..99aed1a44d45 100644 --- a/doc/doxygen/riot.doxyfile +++ b/doc/doxygen/riot.doxyfile @@ -878,7 +878,6 @@ INPUT = ../../doc.txt \ src/build-in-docker.md \ ../../tests/README.md \ src/dev-best-practices.md \ - src/static-vs-dynamic-memory.md \ src/build-system-basics.md \ src/feature_list.md \ src/kconfig/kconfig.md \ diff --git a/doc/doxygen/src/dev-best-practices.md b/doc/doxygen/src/dev-best-practices.md index 88da3429d7a9..125c52a4da42 100644 --- a/doc/doxygen/src/dev-best-practices.md +++ b/doc/doxygen/src/dev-best-practices.md @@ -6,7 +6,7 @@ ## Coding "Dos" and "Don'ts": ### Dos - * Use static memory. See also [Static vs. Dynamic Memory](https://github.com/RIOT-OS/RIOT/wiki/Static-vs-Dynamic-Memory). + * Use static memory. See also [Static vs. Dynamic Memory](#static-vs-dynamic). * Select the priorities carefully. * Minimize stack usage with `DEVELHELP` and `CREATE_STACKTEST`. * Use threads to increase flexibility, modularity, and robustness by leveraging IPC. @@ -87,3 +87,30 @@ The below methodology is recommended, using well-known de facto standard tools f 6. At this stage the implementation has proven bug-free on the native emulator. One can thus finally move on to hardware-in-the-loop, which means (i) flashing the binary on the targeted IoT hardware, typically using standard flasher **OpenOCD** or **edbg**, and (ii) using the **RIOT shell** running on the target IoT device(s) for easier debugging on the target hardware. 7. In case the hardware is not available on-site, one can consider remotely flashing and testing the binary on supported open-access testbeds, e.g. [IoT-LAB](https://www.iot-lab.info) hardware is fully supported by RIOT. 8. In case of failure, after analyzing the failure and attempting to fix the defect, go back to step 1 to make sure the fix did not itself introduce a new defect. + +## Static vs. Dynamic Memory {#static-vs-dynamic} + +In your C program you have to decide where the memory you want to use comes from. +There are two ways to get memory in your C code: + +1. Define static memory. +2. Use dynamic memory (call `malloc()`/`free()` to get memory from the heap). + +Both ways have some drawbacks which are listed here. +If you want to analyze the static memory consumption of your code you can use [otm](https://github.com/LudwigOrtmann/otm) or `make cosy`. + +### Static memory +* Access the memory in one operation O(1) ⇒ real time condition +* Programmer needs to know the amount of memory on compile time + * Leads to over and undersized buffers +* Forces the programmer to think about the amount of need memory at compile time + +### Dynamic memory +* `malloc()` and `free()` are implemented in your `libc` (RIOT on ARM: `newlib`/`picolib`) + * Runtime behavior is not predictable +* Code can request the amount of memory it needs on runtime +* On most platforms: the size of the heap is `sizeof()-sizeof()` + * If you reduce your usage of static memory your heap gets bigger +* On some platforms calling `free()` will not or not always make heap memory available again (see @ref oneway_malloc on MSP430) +* Programmer needs to handle failed memory allocation calls at runtime +* Static code analysis is unable to find errors regarding memory management diff --git a/doc/doxygen/src/static-vs-dynamic-memory.md b/doc/doxygen/src/static-vs-dynamic-memory.md deleted file mode 100644 index c4240dd879ba..000000000000 --- a/doc/doxygen/src/static-vs-dynamic-memory.md +++ /dev/null @@ -1,29 +0,0 @@ -Static vs. Dynamic Memory -========================= - -In your C program you have to decide where the memory you want to use comes from. -There are two ways to get memory in your C code: - -1. Define static memory. -2. Use dynamic memory (call `malloc()`/`free()` to get memory from the heap). - -Both ways have some drawbacks which are listed here. -If you want to analyze the static memory consumption of your code you can use [otm](https://github.com/LudwigOrtmann/otm) or `make cosy`. - -Static memory -------------- -* Access the memory in one operation O(1) ⇒ real time condition -* Programmer needs to know the amount of memory on compile time - * Leads to over and undersized buffers -* Forces the programmer to think about the amount of need memory at compile time - -Dynamic memory --------------- -* `malloc()` and `free()` are implemented in your `libc` (RIOT on ARM: `newlib`/`picolib`) - * Runtime behavior is not predictable -* Code can request the amount of memory it needs on runtime -* On most platforms: the size of the heap is `sizeof()-sizeof()` - * If you reduce your usage of static memory your heap gets bigger -* On some platforms calling `free()` will not or not always make heap memory available again (see @ref oneway_malloc on MSP430) -* Programmer needs to handle failed memory allocation calls at runtime -* Static code analysis is unable to find errors regarding memory management