Skip to content

Move stats API docs to config format #837

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Nov 29, 2018
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 57 additions & 7 deletions docs/api/platform/MbedStats.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,77 @@
## Mbed statistics

Mbed OS provides a set of functions that you can use to capture the memory and thread statistics at runtime. `mbed_stats.h` declares these functions. To enable all Mbed OS statistics, you must build code with the `MBED_ALL_STATS_ENABLED` macro.
Mbed OS provides a set of functions that you can use to capture the memory and thread statistics at runtime. `mbed_stats.h` declares these functions. To enable all Mbed OS platform statistics, you must enable the following Mbed OS configuration option:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Query: Is this information already in the configuration section? If so, instead of duplicating it, can we link to it? If not, why not?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is sort of, it'd require some reading and understanding of how to setup the overrides in JSON. I could just say

enable platform.cpu-stats-enabled

but think this is a bit easier for the user. It does add more things to the page though.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should definitely link to the config page, at least.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please share which config page? Also please new config will not be visible anywhere till code is merged

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Linking to the page in addition to the snippet is a solid idea. This page has a tip note that links to the config page for reference:

https://os.mbed.com/docs/v5.10/tutorials/optimizing.html

```json
{
"target_overrides": {
"*": {
"platform.all-stats-enabled": true
}
}
}
```

<span class="tips">**Tip:** See the documentation of the [Arm Mbed configuration system](../reference/configuration.html) for more details about `mbed_app.json`. </span>

### Memory statistics

You can use memory statistics functions to capture heap usage, cumulative stack usage or stack usage per thread at runtime. To enable memory usage monitoring, you must build Mbed OS with the following macros:
You can use memory statistics functions to capture heap use, cumulative stack use or stack use for each thread at runtime. To enable memory use monitoring, you must enable the following Mbed OS configuration options:

- `MBED_HEAP_STATS_ENABLED`.
- `MBED_STACK_STATS_ENABLED`.
```json
{
"target_overrides": {
"*": {
"platform.heap-stats-enabled": true,
"platform.stack-stats-enabled": true
}
}
}
```

<span class="notes">**Note:** Each `malloc` or `calloc` memory allocation call adds an overhead of 8 bytes when heap memory statistics are enabled.</span>

### Thread statistics

You can use the thread statistics function `mbed_stats_thread_get_each` to capture the thread ID, state, priority, name and stack information for all active threads at runtime. To enable thread monitoring, you must build Mbed OS with the `MBED_THREAD_STATS_ENABLED` macro.
You can use the thread statistics function `mbed_stats_thread_get_each` to capture the thread ID, state, priority, name and stack information for all active threads at runtime. To enable thread monitoring, you must enable the following Mbed OS configuration options:

```json
{
"target_overrides": {
"*": {
"platform.thread-stats-enabled": true
}
}
}
```

### System information

You can use the `mbed_stats_sys_get` function to get the CPU ID, compiler information and RAM and ROM memories on the target device. You must build Mbed OS with the `MBED_SYS_STATS_ENABLED` macro to enable fetching of system information.
You can use the `mbed_stats_sys_get` function to get the CPU ID, compiler information and RAM and ROM memories on the target device. To enable system information fetching, you must enable the following Mbed OS configuration option:

```json
{
"target_overrides": {
"*": {
"platform.sys-stats-enabled": true
}
}
}
```

### CPU statistics

You can use the `mbed_stats_cpu_get` function to get the uptime, idle time and sleep time information. Timing information available is cumulative since the system is on. You must build Mbed OS with the `MBED_CPU_STATS_ENABLED` macro to enable fetching of CPU information. Please note CPU statistics depend on the availability of the low power timer in the hardware.
You can use the `mbed_stats_cpu_get` function to get the uptime, idle time and sleep time information. Timing information available is cumulative because the system is on. Please note CPU statistics depend on the availability of the low power timer in the hardware. To enable fetching of CPU information, you must enable the following Mbed OS configuration option:

```json
{
"target_overrides": {
"*": {
"platform.cpu-stats-enabled": true
}
}
}
```

### Mbed statistics function reference

Expand Down