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

SenRamakri · 2017-10-26T18:30:21Z

No description provided.

SenRamakri · 2017-10-26T18:34:04Z

Note that for Assert and Error functions there are no specific examples code/repo apart from usage example on the help docs. These are simple functions and does not require specific examples to demonstrate their usage and calling these puts the system in error state/stops execution.

0xc0170 · 2017-10-26T19:00:22Z

docs/reference/api/platform/Error.md

@@ -1,5 +1,20 @@
 ## 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. Its declared in mbed_error.h. The function will output the error message when called for the first time, but will ignore subsequent calls without generating any output. 


Might be worth adding that this function invokes exit - termination process .

Sidequestion: I do not remember why are subsequent calls ingored?

Also conditionally compiled with NDEBUG macro (similar note is for assert above)

That's good idea, to add the termination/NDEBUG note.

Currently error function internally uses a static variable which prevents further output if you call again.

0xc0170 · 2017-10-26T19:01:35Z

docs/reference/api/platform/Error.md

+### Error usage example
+The code below uses error function to print a fatal error indicating out of memory condition.
+
+void *operator new(std::size_t count)


shouldn't this use code snippet syntax ?

// code here

0xc0170 · 2017-10-26T19:04:28Z

docs/reference/api/platform/Assert.md

-### Assert example
+### Assert usage example
+
+MBED_ASSERT macro can be used for runtime evaluation of expressions. If the evaluation fails, an error message will be printed out to bash in the below format. Note that MBED_ASSERT macro is available in debug builds only. 


I assume debug builds here means debug + develop profiles?

Good question, I really thought its just debug builds. Let me confirm and update the docs.

AnotherButler

I've reviewed Assert.md so far. Please review my changes to make sure I haven't accidentally changed the meaning of anything. Also, please address my comments and queries. I'll start on the other files tomorrow.

AnotherButler · 2017-10-26T23:51:04Z

docs/reference/api/platform/Assert.md

@@ -1,11 +1,33 @@
 ## Assert


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

AnotherButler · 2017-10-26T23:51:57Z

docs/reference/api/platform/Assert.md

+}
+```
+
+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.


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

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

AnotherButler · 2017-10-26T23:52:29Z

docs/reference/api/platform/Assert.md

-[Add example(s) here.]
+You can use the `MBED_ASSERT` macro for runtime evaluation of expressions. If the evaluation fails, an error message prints to bash in the below format. Note that the `MBED_ASSERT` macro is available in the debug and develop build profiles but not in the release build profile. 
+
+mbed assertation failed: <EVALUATED EXPRESSION>, file: <FILE NAME>, line <LINE NUMBER IN FILE>


Query: Should this be part of the code block that starts on line 17? If not, please put it in code format and give it some context.

Hi Amanda, I fixed the comments but kept the heading as "Assert" since we are explaining the usage/purpose in the doc anyway, also I thought if we change to Mbed Assert, the same applies to many other places as well, so I thought we will keep the heading as Assert. Let me know if you think otherwise.

AnotherButler · 2017-10-26T23:52:58Z

docs/reference/api/platform/Assert.md


-[Add example(s) here.]
+You can use the `MBED_ASSERT` macro for runtime evaluation of expressions. If the evaluation fails, an error message prints to bash in the below format. Note that the `MBED_ASSERT` macro is available in the debug and develop build profiles but not in the release build profile. 


We may want to link to the build profiles page.

AnotherButler

I've reviewed Debug.md. Please review my changes to make sure I didn't accidentally change the meaning of anything. Please also address my comments and queries.

AnotherButler · 2017-10-27T15:50:07Z

docs/reference/api/platform/Debug.md


 ### Debug example

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


@sg- Should this be in the Mbed example teams folder like the other examples?

This example program demonstrates MemoryStats and then have few things to demonstrate debug functions. That's why I have it as a separate example in its own repo. Does that make sense?

Hi Sam,
Yeah, it makes more sense to move it to example teams folder. Ill do that, Thanks for pointing that out.

Hi Sam, Looks like I need permission to publish to mbed_example. When I try to publish "mbed_example" is not showing as a option for me. Can you please add me to the mbed_example repo?

what is your developer account name?

AnotherButler · 2017-10-27T15:51:19Z

docs/reference/api/platform/Debug.md

-[Embed class reference here. If you've never done this before, 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__debug.html)
+
+### Debug functions usage


I like the content in this section, but this section breaks the standardization with the other APIs. Could we make it a second example or move some of the content up to the description area?

I see, yes, we can move it to description area.

AnotherButler · 2017-10-27T15:51:59Z

docs/reference/api/platform/Debug.md


-[Embed class reference here. If you've never done this before, 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__debug.html)


Query: Does this link work for you? I can't get it to work.

Actually it doesn't work now, it depends on my other change coming into mbed-os side.

AnotherButler

I've copy edited the remaining two documents. Please review my edits to make sure I didn't accidentally change the meaning of any content. Please also address my queries and comments.

AnotherButler · 2017-10-27T16:01:09Z

docs/reference/api/platform/Error.md

@@ -1,5 +1,21 @@
 ## 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 causes the application to terminate. `mbed_error.h` declares this error message. Note that the error function outputs the error message in debug and develop builds only. In release builds, the error function does not generate any output, but the application is still be terminated.


Query: Who or what terminates the application? Please clarify for active voice. [Note: I'll fix that extra "be" that I accidentally left in there after I know how to change the passive to active voice.]

Good question, its the mbed-OS error function implementation that terminates the application.

AnotherButler · 2017-10-27T16:01:35Z

docs/reference/api/platform/Error.md

-You can read more about the Error function in [its documentation](https://github.com/ARMmbed/mbed-os/blob/master/platform/mbed_error.h).
+### 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)


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

Again, it depends on my other change coming into mbed-os side.

Awesome. In the description of this PR, could you please list the mbed-os PR#s as dependencies?

AnotherButler · 2017-10-27T16:02:18Z

docs/reference/api/platform/MemoryStats.md

-[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)


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

AnotherButler · 2017-10-27T16:02:38Z

docs/reference/api/platform/MemoryStats.md


 ### MemoryStats example

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


@sg- Should this be in the Mbed example teams folder like the other API examples?

SenRamakri · 2017-10-30T17:46:29Z

Depends on - ARMmbed/mbed-os#5372

sg- · 2017-10-30T18:20:22Z

docs/reference/api/platform/MemoryStats.md

@@ -1,11 +1,15 @@
 ## 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 are some differences between tracing and stats. It would be good to call them out explicitly and explain how each would be used.

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.

AnotherButler · 2017-10-30T23:18:02Z

@SenRamakri What are the PR #s for the mbed-os repo dependencies?

SenRamakri · 2017-10-31T13:27:01Z

@AnotherButler It depends on PR ARMmbed/mbed-os#5372. Please see my comment from yesterday.

Copy edit, mostly for active voice, parallelism and spelling.

Copy edit file, mostly for active voice and punctuation around restrictive clauses.

Copy edit for active voice, branding and consistent tense across docs.

Edit file for active voice, expansion of words and formatting.

AnotherButler · 2017-11-09T19:09:37Z

@SenRamakri Is this ready to merge now, or are there any other dependencies or reviews we still need?

SenRamakri · 2017-11-09T19:48:33Z

This can be merged now as the dependency on mbed-os side is merged.

AnotherButler requested a review from sg- October 26, 2017 18:51

0xc0170 reviewed Oct 26, 2017

View reviewed changes

SenRamakri force-pushed the sen_AssertAndOtherDocs branch from 9168762 to ae65207 Compare October 26, 2017 21:48

AnotherButler added the wait to merge label Oct 26, 2017

AnotherButler reviewed Oct 26, 2017

View reviewed changes

AnotherButler reviewed Oct 27, 2017

View reviewed changes

sg- reviewed Oct 30, 2017

View reviewed changes

AnotherButler added the code dependency label Oct 31, 2017

sg- approved these changes Nov 1, 2017

View reviewed changes

SenRamakri and others added 9 commits November 2, 2017 10:39

MemoryStats, Assert, Debug and Error docs

145a70e

Copy edit Assert.md

9924538

Copy edit, mostly for active voice, parallelism and spelling.

Fix review comments on Assert.md

6eefd33

Copy edit Debug.md

8d01b9f

Copy edit file, mostly for active voice and punctuation around restrictive clauses.

Copy edit Error.md

3c923cb

Copy edit for active voice, branding and consistent tense across docs.

Copy edit MemoryStats.md

e61c654

Edit file for active voice, expansion of words and formatting.

Review comments and example in teams folder

fedfaed

Updated MemoryStats.md

3c31504

Updated MemoryStats.md

bd3c432

SenRamakri force-pushed the sen_AssertAndOtherDocs branch from c692cf1 to bd3c432 Compare November 2, 2017 15:57

AnotherButler removed the code dependency label Nov 9, 2017

AnotherButler approved these changes Nov 9, 2017

View reviewed changes

AnotherButler removed the wait to merge label Nov 9, 2017

AnotherButler merged commit 4c44489 into ARMmbed:new_engine Nov 9, 2017


		[Add example(s) here.]
		You can use the `MBED_ASSERT` macro for runtime evaluation of expressions. If the evaluation fails, an error message prints to bash in the below format. Note that the `MBED_ASSERT` macro is available in the debug and develop build profiles but not in the release build profile.


		[Embed class reference here. If you've never done this before, 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__debug.html)

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

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

Conversation

SenRamakri commented Oct 26, 2017

Uh oh!

SenRamakri commented Oct 26, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xc0170 Oct 26, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SenRamakri commented Oct 30, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

0xc0170 Oct 26, 2017 •

edited

Loading