Documentation of heap_caps_malloc is incorrect (IDFGH-5971)

[jgamble-simple]

According to the documentation:

https://docs.espressif.com/projects/esp-idf/en/release-v3.3/api-reference/system/mem_alloc.html#_CPPv416heap_caps_malloc6size_t8uint32_t

malloc is equivalent to heap_caps_malloc(size, MALLOC_CAP_8BIT).

I have a small piece of code that demonstrates that this is not true:

while (1)
{
    void* p = malloc(1024);
    printf("Malloc another '%p'\n", p);
    if (!p) {
        printf("MALLOC_CAP_8BIT\n");
        heap_caps_print_heap_info(MALLOC_CAP_8BIT);

        void* p = heap_caps_malloc(1024, MALLOC_CAP_8BIT);
        printf("Malloc another (MALLOC_CAP_8BIT) '%p'\n", p);
        while (1) {}
    }
}

This is the tail end of the resulting log:

Malloc another '0x3fffddc4'
Malloc another '0x3fffe1d4'
Malloc another '0x3fffe5e4'
Malloc another '0x3fffe9f4'
Malloc another '0x3fffee04'
Malloc another '0x3ffff214'
Malloc another '0x3ffff624'
Malloc another '0x3ffffa34'
Malloc another '0x0'
Malloc another (MALLOC_CAP_8BIT) '0x3f800024'

I am using platformio, which I believe is using esp-idf version 3.3

[igrr]

Thanks for pointing this out @jgamble-simple, the function description of what malloc does is indeed oversimplified.

The actual behavior of malloc in terms of external RAM allocations depends on CONFIG_SPIRAM_USE choice (https://docs.espressif.com/projects/esp-idf/en/release-v4.3/esp32/api-reference/kconfig.html#config-spiram-use):

• Integrate RAM into memory map (CONFIG_SPIRAM_USE_MEMMAP)
• Make RAM allocatable using heap_caps_malloc(…, MALLOC_CAP_SPIRAM) (CONFIG_SPIRAM_USE_CAPS_ALLOC)
• Make RAM allocatable using malloc() as well (CONFIG_SPIRAM_USE_MALLOC). In this case CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL sets the threshold of allocation size, below which the allocation will be done from internal RAM by default.

I think the description of that function predates these additional configuration options, and was never updated.

Since these options are documented in detail in https://docs.espressif.com/projects/esp-idf/en/release-v4.3/esp32/api-guides/external-ram.html#configuring-external-ram, I think the easiest option is to remove the phrase malloc is equivalent to heap_caps_malloc... from the doxygen comment.