Skip to content

Docs for MemoryStats API, Debug API, Assert and Error APIs #310

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 9 commits into from
Nov 9, 2017
Merged
Show file tree
Hide file tree
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
33 changes: 28 additions & 5 deletions docs/reference/api/platform/Assert.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,34 @@
## Assert
Copy link
Contributor

Choose a reason for hiding this comment

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

Query: Should we change this to "mbed_assert" to match the macro name?


[Add description here.]
Mbed OS provides a set of macros that evaluates an expression and prints an error message if the expression evaluates to false. There are two types of macros, one for evaluating the expression during runtime and one for compile-time evaluation. `mbed_assert.h` defines these macros.

### Assert class reference
### Assert macros reference

[Embed class reference here. If you've never done this, please ask your editor.]
[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/group__platform__Assert.html)

### Assert example
### Assert usage example

[Add example(s) here.]
You can use the `MBED_ASSERT` macro for runtime evaluation of expressions. If the evaluation fails, an error message is printed to STDIO in the below format.
mbed assertation failed: <EVALUATED EXPRESSION>, file: <FILE NAME>, line <LINE NUMBER IN FILE>

Note that the `MBED_ASSERT` macro is available in the debug and develop [build profiles](https://os.mbed.com/docs/v5.6/tools/build-profiles.html) but not in the release build profile.

The below function uses `MBED_ASSERT` to validate a pointer to `serial_t` object.

```C
uint8_t serial_tx_active(serial_t *obj) {
MBED_ASSERT(obj);
...
}
```

You can use the `MBED_STATIC_ASSERT` macro for compile-time evaluation of expressions. If the evaluation fails, the passed in error message prints, and the compilation fails.
Copy link
Contributor

Choose a reason for hiding this comment

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

Query: This says "MBED_STATIC_ASSERT", but the paragraph below says "MBED_ASSERT_STATIC". Are these two separate macros, or is one incorrect?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Good catch, its a typo, let me fix and others. thanks for the review.


The below function uses `MBED_STATIC_ASSERT` to validate the size of the `equeue_timer` structure.

```C
void equeue_tick_init() {
MBED_STATIC_ASSERT(sizeof(equeue_timer) >= sizeof(Timer),"The equeue_timer buffer must fit the class Timer");
...
}
```
28 changes: 24 additions & 4 deletions docs/reference/api/platform/Debug.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,31 @@
## Debug

[Add description here.]
Mbed OS provides a set of debug functions that you can use to output debug messages to `STDIO` at runtime. `mbed_debug.h` declares these functions, which are available only in debug builds.
The `debug` function is a printf-style function that takes a format string followed by arguments. The below are some sample usages.

### Debug class reference
```C
void *operator new(std::size_t count) {
void *buffer = malloc(count);
if (NULL == buffer) {
error("Operator new out of memory\r\n");
} else {
debug("Operator new succeded");
}
return buffer;
}
```
The `debug_if` function is similar to the `debug` function except that it takes an additional argument as its first parameter. The message prints to `STDIO` only if the first paramater evaluates to `true`.

[Embed class reference here. If you've never done this before, please ask your editor.]
```C
void *operator new(std::size_t count) {
debug_if( count == 0, "\nnew called with 0 size");
...
}
```
### Debug functions reference

[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/group__platform__debug.html)

### Debug example

[Add example here.]
[![View Example](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/mbed-os-example-platform-utils/)](https://os.mbed.com/teams/mbed_example/code/mbed-os-example-platform-utils/)
21 changes: 19 additions & 2 deletions docs/reference/api/platform/Error.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,22 @@
## Error

The error function generates a fatal runtime error, which allows the user to dump a message to the serial line, halt the program and place the device in an idle mode with a blinking red LED.
Mbed OS provides an error function to output messages to `STDIO` at runtime when the system encounters a fatal error and the Application calling the error function will be terminated. Note that error function outputs the error message in [Debug and Develop builds](https://os.mbed.com/docs/v5.6/tools/build-profiles.html) only. In release builds, the error function does not generate any `STDIO` output, but the application will still be terminated. `mbed_error.h` declares the error function.

### Error function reference

[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/group__platform__error.html)

### Error example

The code below uses an error function to print a fatal error indicating an out-of-memory condition.

```C
void *operator new(std::size_t count) {
void *buffer = malloc(count);
if (NULL == buffer) {
error("Operator new out of memory\r\n");
}
return buffer;
}
```

You can read more about the Error function in <a href="https://github.com/ARMmbed/mbed-os/blob/master/platform/mbed_error.h" target="_blank">its documentation</a>.
11 changes: 7 additions & 4 deletions docs/reference/api/platform/MemoryStats.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,14 @@
## MemoryStats

[Add description here.]
Mbed OS provides a set of functions that you can use to capture the memory statistics at runtime. `mbed_stats.h` declares these functions. 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.
Copy link
Contributor

Choose a reason for hiding this comment

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

There are some differences between tracing and stats. It would be good to call them out explicitly and explain how each would be used.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Good catch, actually I shouldn't have mentioned MBED_MEM_TRACING_ENABLED at all. There is a separate requirement for writing "mem_trace functions" assigned to Martin. So let me clean this up and remove the references to MBED_MEM_TRACING_ENABLED. I think it should be captured in mem_trace docs, not here.


### MemoryStats class reference
- MBED_HEAP_STATS_ENABLED
- MBED_STACK_STATS_ENABLED

[Add embedded class reference here. If you've never done this, please talk to your editor.]
### MemoryStats functions reference

[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/group__platform__stats.html)
Copy link
Contributor

Choose a reason for hiding this comment

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

Query: Does this link work for you? I see "Page error".


### MemoryStats example

[Add example here.]
[![View Example](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/mbed-os-example-platform-utils/)](https://os.mbed.com/teams/mbed_example/code/mbed-os-example-platform-utils/)