Skip to content
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

API to temporarily enable/disable FileHandles #9797

Merged
merged 4 commits into from Mar 1, 2019

Conversation

@kjbracey-arm
Copy link
Contributor

commented Feb 21, 2019

Description

New API to permit input and/or output to be temporarily disabled on a FileHandle. Implementation for UARTSerial provided.

At present the use of UARTSerial, directly or by setting platform.stdio-buffered-serial, blocks deep sleep because it installs an RxIrq handler for input, and there is no way to indicate that you don't require input (ever, or temporarily) except by destroying the object. And that's not possible if it's the console.

This PR allows you to do mbed_file_handle(STDIN_FILENO)->enable_input(false), which will shut down the reception interrupt pump, and deep sleep can be entered. This is done without losing any serial settings (or any data already in the buffer). The pump is just suspended, permitting power save.

(For this particular common case, should there be a platform.stdio-output-only to do it automatically?)

Pull request type

[ ] Fix
[ ] Refactor
[ ] Target update
[X] Functionality change
[ ] Docs update
[ ] Test update
[ ] Breaking change

Reviewers

@geky, @AriParkkila, @VeijoPesonen, @SeppoTakalo, @pan-

Release Notes

  • UARTSerial can now be temporarily or permanently disabled for input and/or output. This is particularly useful to save power when reception is not required - disabling input permits deep sleep. To do this more generically for the console, use mbed_file_handle(STDIN_FILENO)->enable_input(false).
Add enable API to FileHandle
Add API to dynamically enable/disable input and output on FileHandles.
Aim is to allow power saving by indicating that we permanently or
temporarily do not require input, so that for example serial Rx
interrupts can be released, and deep sleep permitted.
@kjbracey-arm

This comment has been minimized.

Copy link
Contributor Author

commented Feb 21, 2019

As system suspend is going to take a while longer, here's a plan B to cover one of the most commonly-requested power save issues.

@ciarmcom ciarmcom requested review from AriParkkila, geky, pan-, SeppoTakalo, VeijoPesonen and ARMmbed/mbed-os-maintainers Feb 21, 2019

@ciarmcom

This comment has been minimized.

Copy link
Member

commented Feb 21, 2019

@cmonr

This comment has been minimized.

Copy link
Contributor

commented Feb 21, 2019

@kjbracey-arm Spelling errors were discovered in platform/mbed_retarget.h

@0xc0170 0xc0170 added needs: work and removed needs: review labels Feb 22, 2019

Show resolved Hide resolved drivers/UARTSerial.cpp Outdated

@kjbracey-arm kjbracey-arm force-pushed the fh_enable branch from 7d8ec83 to 12ce65c Feb 22, 2019

@kjbracey-arm

This comment has been minimized.

Copy link
Contributor Author

commented Feb 22, 2019

Spelling americanised and TX buffer condition fixed. Topic branch remains in master repo (sorry).

kjbracey-arm added some commits Feb 21, 2019

Implement enable calls in UARTSerial
Implement enable calls so that reception can be shut down to save
power without closing the device.
Add mbed_file_handle lookup function
Add a necessary helper to allow FileHandle objects to be obtained
from POSIX file descriptors.

Primary envisaged use case is to act on STDIN_FILENO etc, eg to
set it non-blocking or use sigio, or to use the enable API.

@kjbracey-arm kjbracey-arm force-pushed the fh_enable branch from 12ce65c to f91d044 Feb 22, 2019

@bulislaw
Copy link
Member

left a comment

Looks good. I'm assuming that all other serial/uart classes are not affecting sleep in the same way (not holding a sleep lock)?

We need to document it, not only in terms of API, but also in context of sleep as it's not obvious. Maybe a note in handbook's power management section?

@kjbracey-arm

This comment has been minimized.

Copy link
Contributor Author

commented Feb 27, 2019

No other current in-tree FileHandles I'm aware of gain by implementing this. But the concept is universally applicable. Good call on specifically bringing this up in the power docs - had only been thinking of FileHandle docs.

@cmonr cmonr added the needs: CI label Feb 28, 2019

@0xc0170

This comment has been minimized.

Copy link
Member

commented Feb 28, 2019

Good call on specifically bringing this up in the power docs - had only been thinking of FileHandle docs.

Please reference this PR in the docs PR

@0xc0170

This comment has been minimized.

Copy link
Member

commented Feb 28, 2019

CI started

@mbed-ci

This comment has been minimized.

Copy link

commented Feb 28, 2019

Test run: FAILED

Summary: 1 of 1 test jobs failed
Build number : 1
Build artifacts

Failed test jobs:

  • jenkins-ci/mbed-os-ci_unittests

@0xc0170 0xc0170 added needs: work and removed needs: CI labels Feb 28, 2019

@deepikabhavnani
Copy link
Contributor

left a comment

Implementation looks fine, but I don't see any test case or even use case where the new functionality is implemented and verified.

_tx_enabed and _rx_enabled are default true, so existing functionality is unchanged.

API's to disable RX and TX are provided by enable_input and enable_output but not used anywhere. My understanding was that we will disable Rx before entering deep sleep (if only UART is blocking it).

Is the intention to leave it completely to application developer to disable serial RTX before deep sleep? Also, it will be good to have test case to verify the new API's.

@kjbracey-arm

This comment has been minimized.

Copy link
Contributor Author

commented Mar 1, 2019

Is the intention to leave it completely to application developer to disable serial RTX before deep sleep?

Yes, or more precisely it allows the application developer to disable serial RX so that deep sleep is possible. We can't deep sleep if serial RX is required, but there's currently no way for the application to indicate they don't need RX (other than closing/destroying the UARTSerial).

My understanding was that we will disable Rx before entering deep sleep (if only UART is blocking it).

That would be nearly equivalent to having enable_input false as default - you'd still need an API to indicate that an app actually needed serial reception. An app could just manually call "deep sleep lock" to do this, but that would be an abstraction/layering error - the application shouldn't need to know the details of how a particular FileHandle interacts with power management. We do need this facility for quite specific "you can deep sleep now" reasons with serial, but the API needs to be generic.

I discussed this more over in #9676 - this is largely addressing that, although it's closed.

Also, it will be good to have test case to verify the new API's.

Indeed - I haven't quite figured out how to do this. I don't think we can easily do it in Greentea, because the debug serial is being driven by a RawSerial, and we can't just take it over. If I can slot into a cpu stats test in the Ice tea framework would be ideal. Or maybe it could be slotted into say an ESP8266 test, where we know we're running on a board with that 2nd serial port connected up.

@kjbracey-arm

This comment has been minimized.

Copy link
Contributor Author

commented Mar 1, 2019

Missing unittest stubs added.

@0xc0170

This comment has been minimized.

Copy link
Member

commented Mar 1, 2019

There's fix incoming for psa, will be on master soon. I'll restart travis and as soon as its green will this go into CI

@0xc0170 0xc0170 added needs: CI and removed needs: work labels Mar 1, 2019

@0xc0170

This comment has been minimized.

Copy link
Member

commented Mar 1, 2019

CI restarted

@deepikabhavnani

This comment has been minimized.

Copy link
Contributor

commented Mar 1, 2019

Indeed - I haven't quite figured out how to do this. I don't think we can easily do it in Greentea,

Assuming we will have test later, can we add the use case of new API as an example for docs? Along with API docs.

CC @AnotherButler

@mbed-ci

This comment has been minimized.

Copy link

commented Mar 1, 2019

Test run: SUCCESS

Summary: 13 of 13 test jobs passed
Build number : 2
Build artifacts

@0xc0170 0xc0170 added ready for merge and removed needs: CI labels Mar 1, 2019

@0xc0170

This comment has been minimized.

Copy link
Member

commented Mar 1, 2019

@AnotherButler Please review (we will fix docs in separate PR as it's close to the code freeze and we have still some work to do there).

@0xc0170

0xc0170 approved these changes Mar 1, 2019

@0xc0170

This comment has been minimized.

Copy link
Member

commented Mar 1, 2019

Indeed - I haven't quite figured out how to do this. I don't think we can easily do it in Greentea, because the debug serial is being driven by a RawSerial, and we can't just take it over. If I can slot into a cpu stats test in the Ice tea framework would be ideal. Or maybe it could be slotted into say an ESP8266 test, where we know we're running on a board with that 2nd serial port connected up.

Is this tracked anywhere?

@0xc0170 0xc0170 merged commit 596b9f7 into master Mar 1, 2019

29 checks passed

continuous-integration/jenkins/pr-head This commit looks good
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details
jenkins-ci/build-ARMC5 Success
Details
jenkins-ci/build-ARMC6 Success
Details
jenkins-ci/build-GCC_ARM Success
Details
jenkins-ci/build-IAR8 Success
Details
jenkins-ci/cloud-client-test Success
Details
jenkins-ci/dynamic-memory-usage RTOS ROM(+24 bytes) RAM(+0 bytes)
Details
jenkins-ci/exporter Success
Details
jenkins-ci/greentea-test Success
Details
jenkins-ci/mbed2-build-ARMC5 Success
Details
jenkins-ci/mbed2-build-ARMC6 Success
Details
jenkins-ci/mbed2-build-GCC_ARM Success
Details
jenkins-ci/mbed2-build-IAR8 Success
Details
jenkins-ci/unittests Success
Details
travis-ci/astyle Local astyle testing has passed
Details
travis-ci/docs Local docs testing has passed
Details
travis-ci/doxy-spellcheck Local doxy-spellcheck testing has passed
Details
travis-ci/events Passed, runtime is 9143 cycles (-1235 cycles)
Details
travis-ci/gitattributestest Local gitattributestest testing has passed
Details
travis-ci/include_check Local include_check testing has passed
Details
travis-ci/licence_check Local licence_check testing has passed
Details
travis-ci/littlefs Passed, code size is 8408B (+0.00%)
Details
travis-ci/psa-autogen Local psa-autogen testing has passed
Details
travis-ci/tools-py2.7 Local tools-py2.7 testing has passed
Details
travis-ci/tools-py3.5 Local tools-py3.5 testing has passed
Details
travis-ci/tools-py3.6 Local tools-py3.6 testing has passed
Details
travis-ci/tools-py3.7 Local tools-py3.7 testing has passed
Details

@0xc0170 0xc0170 removed the ready for merge label Mar 1, 2019

@cmonr

This comment has been minimized.

Copy link
Contributor

commented Mar 5, 2019

kjbracey-arm added a commit to kjbracey-arm/mbed-os-5-docs that referenced this pull request Mar 6, 2019

kjbracey-arm added a commit to kjbracey-arm/mbed-os-5-docs that referenced this pull request Mar 6, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.