Espressif ESP32-S2 User Manual

Chapter 2. API Reference
• For buffer overflows, heap tracing in HEAP_TRACE_ALL mode lets you see which callers are allocating which
addresses from the heap. See Heap Tracing To Find Heap Corruption for more details. If you can find the
function which allocates memory with an address immediately before the address which is corrupted, this will
probably be the function which overflows the buffer.
• Calling heap_caps_dump() or heap_caps_dump_all() can give an indication of what heap blocks
are surrounding the corrupted region and may have overflowed/underflowed/etc.
Configuration Temporarily increasing the heap corruption detection level can give more detailed information about
heap corruption errors.
In the project configuration menu, under Component config there is a menu Heap memory debugging.
The setting CONFIG_HEAP_CORRUPTION_DETECTION can be set to one of three levels:
Basic (no poisoning) This is the default level. No special heap corruption features are enabled, but provided
assertions are enabled (the default configuration) then a heap corruption error will be printed if any of the heap’s
internal data structures appear overwritten or corrupted. This usually indicates a buffer overrun or out of bounds
write.
If assertions are enabled, an assertion will also trigger if a double-free occurs (the same memory is freed twice).
Calling heap_caps_check_integrity() in Basic mode will check the integrity of all heap structures, and
print errors if any appear to be corrupted.
Light Impact At this level, heap memory is additionally “poisoned”with head and tail “canary bytes”before
and after each block which is allocated. If an application writes outside the bounds of allocated buffers, the canary
bytes will be corrupted and the integrity check will fail.
The head canary word is 0xABBA1234 (3412BAAB in byte order), and the tail canary word is 0xBAAD5678
(7856ADBA in byte order).
“Basic”heap corruption checks can also detect most out of bounds writes, but this setting is more precise as even a
single byte overrun can be detected. With Basic heap checks, the number of overrun bytes before a failure is detected
will depend on the properties of the heap.
Enabling “Light Impact”checking increases memory usage, each individual allocation will use 9 to 12 additional
bytes of memory (depending on alignment).
Each time free() is called in Light Impact mode, the head and tail canary bytes of the buffer being freed are
checked against the expected values.
When heap_caps_check_integrity() is called, all allocated blocks of heap memory have their canary bytes
checked against the expected values.
In both cases, the check is that the first 4 bytes of an allocated block (before the buffer returned to the user) should
be the word 0xABBA1234. Then the last 4 bytes of the allocated block (after the buffer returned to the user) should
be the word 0xBAAD5678.
Different values usually indicate buffer underrun or overrun, respectively.
Comprehensive This level incorporates the “light impact”detection features plus additional checks for
uninitialised-access and use-after-free bugs. In this mode, all freshly allocated memory is filled with the pattern
0xCE, and all freed memory is filled with the pattern 0xFE.
Enabling “Comprehensive”detection has a substantial runtime performance impact (as all memory needs to be set
to the allocation patterns each time a malloc/free completes, and the memory also needs to be checked each time.)
However it allows easier detection of memory corruption bugs which are much more subtle to find otherwise. It is
recommended to only enable this mode when debugging, not in production.
Espressif Systems 985
Submit Document Feedback
Release v4.4

Espressif ESP32-S2 Specifications

General

Brand	Espressif
Model	ESP32-S2
Category	Single board computers
Language	English