107 lines
2.8 KiB
Markdown
107 lines
2.8 KiB
Markdown
|
# Heaptrace Module
|
||
|
|
| Since | Origin / Contributor | Maintainer | Source |
|
||
|
|
| :----- | :-------------------- | :---------- | :------ |
|
||
|
|
| 2021-09-16 | [Johny Mattsson](https://github.com/jmattsson) |[Johny Mattsson](https://github.com/jmattsson) | [heaptrace.c](../../components/modules/heaptrace.c)|
|
||
|
|
|
||
|
|
The heaptrace module is a debug aid for diagnosing heap allocations and
|
||
|
|
leaks thereof. It provides an interface to the [built-in heap tracing
|
||
|
|
support in the IDF](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/heap_debug.html), enabling interactive heap tracing
|
||
|
|
from the Lua command line.
|
||
|
|
|
||
|
|
To use this module, "standalone" heap tracing must be enabled in Kconfig
|
||
|
|
first. This setting is found (at the time of writing) under
|
||
|
|
"Component config" > "Heap memory debugging" > "Heap tracing". The depth
|
||
|
|
of the call chain to capture can also be configured there. It can be very
|
||
|
|
beneficial to set that to its max, but it comes at significantly increased
|
||
|
|
memory requirements in turn.
|
||
|
|
|
||
|
|
A typical sequence of commands for a heap tracing session will be:
|
||
|
|
```lua
|
||
|
|
heaptrace.init(200) -- your needed buffer size will depend on your use case
|
||
|
|
collectgarbage() -- start with as clean a slate as possible
|
||
|
|
heaptrace.start(heaptrace.TRACE_LEAKS) -- start in leak tracing mode
|
||
|
|
heaptrace.dump() -- dump the current state of allocations
|
||
|
|
... -- do the thing that is leaking memory
|
||
|
|
collectgarbage() -- free things that can be freed, to avoid false positives
|
||
|
|
heaptrace.stop() -- optional, but provides higher quality output next
|
||
|
|
heaptrace.dump() -- dump the current state of allocations, hopefully showing the leaked entries and where they got allocated from
|
||
|
|
-- heaptrace.resume() -- optionally resume the tracing, if stopped previously
|
||
|
|
```
|
||
|
|
|
||
|
|
## heaptrace.init
|
||
|
|
Allocates and registers the heap tracing buffer.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
```lua
|
||
|
|
heaptrace.init(bufsz)
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
- `bufsz` the size of the heap tracing buffer, expressed as number of heap tracing records. The actual size depends on the call chain depth configured in Kconfig.
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|
||
|
|
|
||
|
|
|
||
|
|
## heaptrace.start
|
||
|
|
Starts the heap tracing. All allocations and frees will be recorded in the
|
||
|
|
heap tracing buffer, subject to availability within the buffer.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
```lua
|
||
|
|
heaptrace.start(mode)
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
- `mode` the heap tracing mode to use. One of:
|
||
|
|
- `heaptrace.TRACE_LEAKS`
|
||
|
|
- `heaptrace.TRACE_ALL`
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|
||
|
|
|
||
|
|
|
||
|
|
## heaptrace.stop
|
||
|
|
Stops the heap tracing session. A stopped session may be resumed later.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
```lua
|
||
|
|
heaptrace.stop()
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
None.
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|
||
|
|
|
||
|
|
|
||
|
|
## heaptrace.resume
|
||
|
|
Resumes a previously stopped heap tracing session.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
```lua
|
||
|
|
heaptrace.resume()
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
None.
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|
||
|
|
|
||
|
|
|
||
|
|
## heaptrace.dump
|
||
|
|
Dumps the heap trace buffer to the console.
|
||
|
|
|
||
|
|
#### Syntax
|
||
|
|
```lua
|
||
|
|
heaptrace.dump()
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Parameters
|
||
|
|
None.
|
||
|
|
|
||
|
|
#### Returns
|
||
|
|
`nil`
|