mbed_wait_api: add comments to warn the func will lock deep sleep #6645

woodsking2 · 2018-04-16T10:19:14Z

Description

Add some comments to warn the wait() will lock deep sleep.

Pull request type

[X] Fix
[ ] Refactor
[ ] New target
[ ] Feature
[ ] Breaking change

discuss: #6574

cmonr

Minor grammer nits.

cmonr · 2018-04-17T02:53:14Z

platform/mbed_wait_api.h

@@ -53,18 +53,27 @@ extern "C" {
 *  the accuracy of single precision floating point).
 *
 *  @param s number of seconds to wait
+ * 
+ *  @note
+ *    This func will lock the deep sleep, if you want device entry deep sleep mode, please use Thread::wait()


Minor grammer nits.

"This func will lock deep sleep. If you want device entry deep sleep mode, please use Thread::wait()"

Updated

kjbracey · 2018-04-17T09:20:56Z

I'd still rather we fixed this than documented it.

If documenting it, I'd want the other feature documented, which is that wait_ms() and wait(float) always spin to get an exact number of microseconds, potentially impacting power and multi-thread performance. Again, avoided by Thread::wait().

…to get an exact number of microseconds, potentially impacting power and multi-thread performance. Again, avoided by Thread::wait()".

0xc0170 · 2018-04-17T12:43:04Z

Thanks @woodsking2 for the update

@AnotherButler Please review the docs update

AnotherButler

I've left a few changes. Also, should we leave a note here: https://os-doc-builder.test.mbed.com/docs/development/reference/wait.html?

AnotherButler · 2018-04-17T20:30:37Z

platform/mbed_wait_api.h

 */
 void wait_ms(int ms);

 /** Waits a number of microseconds.
 *
 *  @param us the whole number of microseconds to wait
+ * 
+ *  @note
+ *    This func always spin to get an exact number of microseconds, potentially 


Please change to "This function always spins to get the exact number of microseconds, which potentially affects power (such as preventing deep sleep) and multithread performance."

AnotherButler · 2018-04-17T20:31:10Z

platform/mbed_wait_api.h

 */
 void wait(float s);

 /** Waits a number of milliseconds.
 *
 *  @param ms the whole number of milliseconds to wait
+ * 
+ *  @note
+ *    This func always spin to get an exact number of microseconds, potentially 


Please change to "This function always spins to get the exact number of microseconds, which potentially affects power (such as preventing deep sleep) and multithread performance. You can avoid it by using Thread::wait()."

AnotherButler · 2018-04-17T20:31:17Z

platform/mbed_wait_api.h

@@ -53,18 +53,32 @@ extern "C" {
 *  the accuracy of single precision floating point).
 *
 *  @param s number of seconds to wait
+ * 
+ *  @note
+ *    This func always spin to get an exact number of microseconds, potentially 


Please change to "This function always spins to get the exact number of microseconds, which potentially affects power (such as preventing deep sleep) and multithread performance. You can avoid it by using Thread::wait()."

…to get the exact number of microseconds, which potentially affects power (such as preventing deep sleep) and multithread performance. You can avoid it by using Thread::wait()."

0xc0170 · 2018-04-18T09:04:36Z

I've left a few changes. Also, should we leave a note here: https://os-doc-builder.test.mbed.com/docs/development/reference/wait.html?

Yes, we should update.

@woodsking2 Can you send a patch to docs to update this once this is integrated?

Testing now

/morph build

kjbracey · 2018-04-18T09:07:15Z

I already see a note:

Avoiding OS delay

When you call wait, your board's CPU is in a loop waiting for the required time to pass. Using the Arm Mbed RTOS, you can make a call to Thread::wait instead.

That's not 100% accurate - it will sleep in the RTOS for the whole number of milliseconds, then spin as needed to make the necessary fraction of a millisecond. But it blocks the platform deep sleep for the entire duration.

mbed-ci · 2018-04-18T09:37:29Z

Build : SUCCESS

Build number : 1783
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/6645/

Triggering tests

/morph test
/morph uvisor-test
/morph export-build
/morph mbed2-build

woodsking2 · 2018-04-18T11:07:23Z

@0xc0170 Sorry, I don't know how send a patch and I can't open https://os-doc-builder.test.mbed.com

0xc0170 · 2018-04-18T12:29:43Z

@orenc17 CAn you please review last 10 runs in uvisor (one device failed few times there)

/morph uvisor-test

mbed-ci · 2018-04-18T17:10:57Z

Exporter Build : ABORTED

Build number : 1428
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/exporter/6645/

mbed-ci · 2018-04-18T17:35:36Z

Test : SUCCESS

Build number : 1593
Test logs :http://mbed-os-logs.s3-website-us-west-1.amazonaws.com/?prefix=logs/6645/1593

0xc0170 · 2018-04-19T08:16:32Z

/morph export-build
/morph mbed2-build

mbed-ci · 2018-04-19T11:14:13Z

Exporter Build : SUCCESS

Build number : 1442
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/exporter/6645/

0xc0170 · 2018-04-20T11:13:36Z

I've left a few changes. Also, should we leave a note here: https://os-doc-builder.test.mbed.com/docs/development/reference/wait.html?

@AnotherButler Can you update it based on this ? This one - approved or changes required?

adbridge · 2018-04-30T11:37:06Z

@woodsking2 Please do not modify the structure of the PR body. I have edited it to put it back to how it should be. Thanks

adbridge · 2018-04-30T11:38:49Z

@AnotherButler Could you please address @0xc0170 comments above? Thanks

AnotherButler · 2018-04-30T19:02:54Z

So, if I'm understanding correctly, I should change the Handbook Wait page warning from:

"When you call wait, your board's CPU is in a loop waiting for the required time to pass. Using the Arm Mbed RTOS, you can make a call to Thread::wait instead."

to:

"When you call wait, your board's CPU will sleep in the RTOS for the whole number of milliseconds and then spin to make the necessary fraction of a millisecond. However, it blocks the platform deep sleep for the entire duration."

Is that right?

kjbracey · 2018-05-02T10:46:22Z

That's accurate for the current RTOS implementation.

0xc0170 · 2018-05-02T11:42:56Z

@bulislaw / @SenRamakri Please review the latest update.

SenRamakri · 2018-05-02T12:08:13Z

platform/mbed_wait_api.h

+ *  @note
+ *    This function always spins to get the exact number of microseconds, 
+ *    which potentially affects power (such as preventing deep sleep) and multithread performance. 
+ *    You can avoid it by using Thread::wait().


Hi @woodsking2 - The rtos based implementation of this function does call Thread::wait. So this comment is not broadly applicable.

…" comments

woodsking2 · 2018-05-03T02:35:33Z

@SenRamakri
Add "If the RTOS is present, " comments.
Please review.

cmonr · 2018-05-08T01:14:07Z

/morph build

mbed-ci · 2018-05-08T01:56:33Z

Build : SUCCESS

Build number : 1941
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/6645/

Triggering tests

/morph test
/morph uvisor-test
/morph export-build
/morph mbed2-build

mbed-ci · 2018-05-08T10:15:12Z

Exporter Build : SUCCESS

Build number : 1588
Build artifacts/logs : http://mbed-os.s3-website-eu-west-1.amazonaws.com/?prefix=builds/exporter/6645/

mbed-ci · 2018-05-08T10:44:17Z

Test : SUCCESS

Build number : 1763
Test logs :http://mbed-os-logs.s3-website-us-west-1.amazonaws.com/?prefix=logs/6645/1763

0xc0170 · 2018-05-08T11:07:14Z

/morph mbed2-build

mbed_wait_api: add comments to warn the func will lock deep sleep

4c69419

0xc0170 requested review from bulislaw, c1728p9 and SenRamakri April 16, 2018 10:37

0xc0170 added the needs: review label Apr 16, 2018

bulislaw previously approved these changes Apr 16, 2018

View reviewed changes

cmonr previously requested changes Apr 17, 2018

View reviewed changes

accept Cruz Monrreal's review

efc228f

woodsking2 dismissed bulislaw’s stale review via efc228f April 17, 2018 07:23

0xc0170 previously approved these changes Apr 17, 2018

View reviewed changes

Accept Kevin Bracey's review, "wait_ms() and wait(float) always spin …

0462799

…to get an exact number of microseconds, potentially impacting power and multi-thread performance. Again, avoided by Thread::wait()".

woodsking2 dismissed 0xc0170’s stale review via 0462799 April 17, 2018 10:12

0xc0170 requested a review from AnotherButler April 17, 2018 12:42

AnotherButler reviewed Apr 17, 2018

View reviewed changes

accept Amanda Butler's review. change to "This function always spins …

27ce443

…to get the exact number of microseconds, which potentially affects power (such as preventing deep sleep) and multithread performance. You can avoid it by using Thread::wait()."

kjbracey previously approved these changes Apr 18, 2018

View reviewed changes

0xc0170 approved these changes Apr 18, 2018

View reviewed changes

0xc0170 added needs: CI and removed needs: review labels Apr 18, 2018

0xc0170 added needs: review and removed needs: CI labels Apr 19, 2018

0xc0170 previously approved these changes May 2, 2018

View reviewed changes

SenRamakri reviewed May 2, 2018

View reviewed changes

mbed_wait_api: wait_ms() wait() wait_us() add "If the RTOS is present…

c9b2640

…" comments

woodsking2 dismissed stale reviews from 0xc0170 and kjbracey via c9b2640 May 3, 2018 02:23

0xc0170 approved these changes May 3, 2018

View reviewed changes

cmonr added needs: CI and removed needs: review labels May 8, 2018

cmonr approved these changes May 8, 2018

View reviewed changes

cmonr added ready for merge release-version: 5.8.5 and removed needs: CI labels May 8, 2018

cmonr merged commit 68ad00f into ARMmbed:master May 8, 2018

cmonr removed the ready for merge label May 8, 2018

mbed_wait_api: add comments to warn the func will lock deep sleep #6645

mbed_wait_api: add comments to warn the func will lock deep sleep #6645

Uh oh!

Conversation

woodsking2 commented Apr 16, 2018 • edited by adbridge Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Pull request type

Uh oh!

cmonr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kjbracey commented Apr 17, 2018

Uh oh!

0xc0170 commented Apr 17, 2018

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!

0xc0170 commented Apr 18, 2018

Uh oh!

kjbracey commented Apr 18, 2018

Uh oh!

mbed-ci commented Apr 18, 2018

Triggering tests

Uh oh!

woodsking2 commented Apr 18, 2018

Uh oh!

0xc0170 commented Apr 18, 2018

Uh oh!

mbed-ci commented Apr 18, 2018

Uh oh!

mbed-ci commented Apr 18, 2018

Uh oh!

0xc0170 commented Apr 19, 2018

Uh oh!

mbed-ci commented Apr 19, 2018

Uh oh!

0xc0170 commented Apr 20, 2018

Uh oh!

adbridge commented Apr 30, 2018

Uh oh!

adbridge commented Apr 30, 2018

Uh oh!

AnotherButler commented Apr 30, 2018

Uh oh!

kjbracey commented May 2, 2018

Uh oh!

0xc0170 commented May 2, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

woodsking2 commented May 3, 2018

Uh oh!

cmonr commented May 8, 2018

Uh oh!

mbed-ci commented May 8, 2018

Triggering tests

Uh oh!

mbed-ci commented May 8, 2018

Uh oh!

mbed-ci commented May 8, 2018

Uh oh!

0xc0170 commented May 8, 2018

Uh oh!

Uh oh!

woodsking2 commented Apr 16, 2018 •

edited by adbridge

Loading