-
Notifications
You must be signed in to change notification settings - Fork 178
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
Changes from all commits
145a70e
9924538
6eefd33
8d01b9f
3c923cb
e61c654
fedfaed
3c31504
bd3c432
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,11 +1,34 @@ | ||
## Assert | ||
|
||
[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.] | ||
[](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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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? There was a problem hiding this comment. Choose a reason for hiding this commentThe 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"); | ||
... | ||
} | ||
``` |
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 | ||
|
||
[](https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/group__platform__debug.html) | ||
|
||
### Debug example | ||
|
||
[Add example here.] | ||
[](https://os.mbed.com/teams/mbed_example/code/mbed-os-example-platform-utils/) |
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 | ||
|
||
[](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>. |
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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
||
[](https://os.mbed.com/docs/v5.6/mbed-os-api-doxy/group__platform__stats.html) | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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.] | ||
[](https://os.mbed.com/teams/mbed_example/code/mbed-os-example-platform-utils/) |
There was a problem hiding this comment.
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?