Heap & Memory Allocation Statistics: add mallinfo support & better dynamic memory documentation

[htcrane]

Is your enhancement proposal related to a problem? Please describe. 1) The documentation does not make it obviously clear if using malloc() or k_malloc() is the preferred method for dynamic memory allocation. 2) There currently is no clean way of getting heap statistics for the standard library, such as with mallinfo().

Describe the solution you'd like 1) Provide the user with a standard library function to understand how much memory is left for allocation via malloc().

• This could be completed through added support for mallinfo() for structure statistics and malloc_stats() for printed statistics (newlib C, section 3.25).
• Completion by adding the _mallinfo() and _malloc_stats() stubs for the standard library.
• For newlib, this could be achieved in /lib/libc/newlib/libc-hooks.c by using existing variables: HEAP_BASE and heap_sz.

2) Provide clear documentation on why a user may want to use malloc() directly or stick to k_malloc().

• To my understanding...
  • malloc() is general purpose and supported no matter the standard C library chosen to build with. The memory sourced may go through a virtualization step where memory may no longer be continuous regions.
  • k_malloc() requires additional setup through the CONFIG_HEAP_MEM_POOL_SIZE option and is useful if memory should be allocated from a common memory region.
• If this is correct, this should be stated in the documentation directly so others do not need to sift through multiple function calls to figure out what the difference is. Why one may be better for a task than the other.

3) Provide a memory summary documentation page. Looking through several issues, conversations about the heap talk about the heap available to the standard c libraries (malloc) and the system heap (k_alloc) interchangeably when they do not source their memory from the same heap.

Describe alternatives you've considered

• Currently no way to know how much memory is left for malloc() or other heap statistics available to the standard library.
• Previous issues of such discussions about stats for malloc:

  • 29735

  • 23076

  • 57725

Additional context

• Zephyr currently implements a heap size function for the user-defined system heap: sys_heap_runtime_stats_get() shown in this sample. This function does not appear anywhere in the latest Zephyr documentation.
• The kernel shell service that uses aforementioned function above cmd_kernel_heap(), code link, also does not appear anywhere in the latest Zephyr documentation. It provides stats for the _system_heap, which is used for k_malloc(). This is useful for that single memory region, which is not the same memory region as heap_base where malloc() is sourcing its memory from (when using newlib).

[github-actions[bot]]

Hi @htcrane! We appreciate you submitting your first issue for our open-source project. 🌟

Even though I'm a bot, I can assure you that the whole community is genuinely grateful for your time and effort. 🤖💙

[htcrane]

If my understanding is correct, I can open a PR to add the stubs and add some clearer documentation.