feat(esp-alloc): Add heap usage stats

[AnthonyGrondin]

Thank you for your contribution!

We appreciate the time and effort you've put into this pull request.
To help us review it efficiently, please ensure you've gone through the following checklist:

Submission Checklist 📝

• I have updated existing examples or added new ones (if applicable).
• I have used cargo xtask fmt-packages command to ensure that all changed code is formatted correctly.
• My changes were added to the CHANGELOG.md in the proper section.
• I have added necessary changes to user code to the Migration Guide.
• My changes are in accordance to the esp-rs API guidelines

Extra:

• I have read the CONTRIBUTING.md guide and followed its instructions.

Pull Request Details 📖

Description

This PR provides a way to easily see the current heap usage of esp_alloc. This adds HeapRegion::stats() and EspHeap::stats(), to return RegionStats and HeapStats respectively.

Both also implement core::fmt::Display to easily pretty-print the heap usage as following:

println!("{}", esp_alloc::get_info!());

HEAP INFO
Size: 117760
Current usage: 47280
Max usage: 70060
Total freed: 103012
Total allocated: 150292
Memory Layout: 
Internal | ██████████████░░░░░░░░░░░░░░░░░░░░░ | Used: 47280 / Total: 117760 (Free: 70480)
Unused   | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |
Unused   | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |

Testing

I have tested with a few examples locally and with esp-mbedtls, and everything works fine.
I haven't tested with PSRAM as I don't have any.

[bugadani]

Fancy, but it should also support defmt, not everybody uses esp-println and making the user add Display2Format makes this somewhat less elegant.

[bjoernQ]

Looks nice.

Given this runs a small amount of code every time allloc/dealloc is called would it make sense to have that feature gated?

[MabezDev]

This looks lovely! I agree with @bjoernQ though that this should be an opt-in feature.

[okhsunrog]

@bugadani won't this work with defmt?
defmt::!println!("{}", esp_alloc::get_info!());

[AnthonyGrondin]

I was thinking about feature gating the whole get_info!() + HeapStats feature, but I realized that the extra computation in alloc/dealloc is only to keep track of internal heap stats. I added a new feature named internal-heap-stats (for the lack of better name), to cover this.

The trade-off is that we have a feature that will change the amount of fields returned by the struct, if a user calls stats(), but I think we do that in a few places already.

I also found a chip that has PSRAM, so I tested with using an internal heap and a PSRAM heap, and the output looks like the following:

HEAP INFO
Size: 2148352
Current usage: 512028
Max usage: 512028
Total freed: 0
Total allocated: 512028
Memory Layout: 
Internal | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ | Used: 28 / Total: 51200 (Free: 51172)
External | ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░ | Used: 512000 / Total: 2097152 (Free: 1585152)
Unused   | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |

[AnthonyGrondin]

Fancy, but it should also support defmt, not everybody uses esp-println and making the user add Display2Format makes this somewhat less elegant.

I'm not used to defmt, can you tell what changes are required to make it work with defmt? The following was suggested by @okhsunrog in #2137 (comment):
defmt::!println!("{}", esp_alloc::get_info!());

The examples aren't set up to use defmt so I'll have to create a project that uses defmt.

[bugadani]

With the obvious syntax error, I believe the compiler would just complain about "HeapStats does not implement Format".

How you may do it.

This would also need to be feature gated, similar to how the rest of the crates have a demft feature. We can also do it later if you don't feel comfortable experimenting just for a different printing framework.

[okhsunrog]

@bugadani yeah, that was a typo, sorry. For some reason I also thought that core Debug can also be used for defmt's println. Seems like it's not the case.. After stydying the docs a bit I think now I get it right

[jessebraham]

Thanks, LGTM!

Comments have been addressed

[MabezDev]

Whilst convenient, this will end up pulling in core::fmt for defmt users, could you just duplicate the fmt impl using the defmt::write! macro instead?

[MabezDev]

Sorry, not quite, we should manually impl defmt to avoid pulling in core::fmt machinery for end users

[okhsunrog]

@MabezDev maybe we can merge it as it is and I'll implement defmt correctly in a follow up PR?