Last Comment Bug 708964 - Create API to manage the power usage of the device
: Create API to manage the power usage of the device
Status: RESOLVED FIXED
: dev-doc-complete
Product: Core
Classification: Components
Component: DOM (show other bugs)
: unspecified
: All Gonk (Firefox OS)
: -- normal (vote)
: ---
Assigned To: Nobody; OK to take it and work on it
:
: Andrew Overholt [:overholt]
Mentors:
Depends on: 697132 709585 710135 739913 751004
Blocks: webapi
  Show dependency treegraph
 
Reported: 2011-12-08 22:52 PST by Kan-Ru Chen [:kanru] (UTC+8)
Modified: 2013-02-19 05:38 PST (History)
12 users (show)
See Also:
Crash Signature:
(edit)
QA Whiteboard:
Iteration: ---
Points: ---
Has Regression Range: ---
Has STR: ---


Attachments
01 (5.42 KB, patch)
2011-12-12 20:18 PST, Kan-Ru Chen [:kanru] (UTC+8)
no flags Details | Diff | Splinter Review
02 (2.64 KB, patch)
2011-12-12 20:19 PST, Kan-Ru Chen [:kanru] (UTC+8)
no flags Details | Diff | Splinter Review
03 (10.17 KB, patch)
2011-12-12 20:19 PST, Kan-Ru Chen [:kanru] (UTC+8)
no flags Details | Diff | Splinter Review
04 (11.28 KB, patch)
2011-12-12 20:20 PST, Kan-Ru Chen [:kanru] (UTC+8)
no flags Details | Diff | Splinter Review
05 (4.25 KB, patch)
2011-12-12 20:20 PST, Kan-Ru Chen [:kanru] (UTC+8)
no flags Details | Diff | Splinter Review
06 (1.21 KB, patch)
2011-12-12 20:20 PST, Kan-Ru Chen [:kanru] (UTC+8)
no flags Details | Diff | Splinter Review

Description Kan-Ru Chen [:kanru] (UTC+8) 2011-12-08 22:52:20 PST
Inspired by http://developer.android.com/reference/android/os/PowerManager.html

The idea is to create a DOM API to control the power consumed by the device, from adjusting the screen brightness to turning the power off. And we need a way to track the user activity and try to put the device into low power state when the user is idle.

Current interface:

interface nsIDOMMozPowerManager : nsISupports {
    attribute double        screenBrightness;
    attribute boolean       screenEnabled;
    attribute unsigned long timeout;

    void              sleep();
    void              powerOff(in boolean reboot);
    void              userActivity(in boolean aNoChangeLights);
    [implicit_jscontext]
    nsIDOMMozWakeLock requestWakeLock(in jsval policy, in ACString id);
    //
    // policy = { cpu: "on",
    //            screen: "dim", "bright", "off", "on",
    //            keyboard: "on", "off",
    //            wakeup: "on" }
};

interface nsIDOMMozWakeLock : nsISupports {
    readonly attribute boolean isHeld;
    void                       unlock();
};
Comment 1 Justin Lebar (not reading bugmail) 2011-12-09 00:45:26 PST
Some questions about this API:

What is |timeout|?  screenTimeout?

What does userActivity() do?  Is that what I'm supposed to call when the user does something?  If so, maybe we could improve that name.  Also, what does the boolean do?  (I have a personal vendetta against functions which take opaque boolean args, so maybe we can split this into two functions.)

Do we need both screenEnabled and sleep()?  If I call sleep() while holding the appropriate wake lock, we'll only turn off the display, right?  Is there a way to programmatically wake up after calling sleep()?

I'd prefer powerOff() and reboot() as separate functions.

With respect to the wake lock policy:
  * Do "cpu" and "wakeup" always need to be "on"?  Is there another option?
  * What's the difference between "screen: dim" and "screen: on"?  In both cases, I'm requesting that the screen not automatically turn off, right?

The big question here is: How much of our power management are we going to do in JS?  I suspect, for example, that we'll manage the screen's brightness from JS.  In that case, then we need an API for reading whether there are any wake locks held on the screen, and we probably don't need the |timeout| property.

In fact, the API that content can touch (requestWakeLock) should almost certainly be separate from the API that privileged code touches.
Comment 2 Justin Lebar (not reading bugmail) 2011-12-11 19:16:50 PST
Kan-Ru, you'll probably have an easier time getting these changes in if you break this API up into smaller pieces and address them in separate bugs:

 * reboot / shutdown
 * moving screenEnabled / screenBrightness
 * wake locks / idle notification

I'd probably do wake lock / idle notification last, because that's going to be tricky.
Comment 3 Justin Lebar (not reading bugmail) 2011-12-11 19:39:24 PST
See also discussion in https://github.com/andreasgal/gaia/issues/167
Comment 4 Kan-Ru Chen [:kanru] (UTC+8) 2011-12-11 20:25:06 PST
(In reply to Justin Lebar [:jlebar] from comment #1)
> Some questions about this API:
> 
> What is |timeout|?  screenTimeout?

Yes. The timeout before screen locks.

> What does userActivity() do?  Is that what I'm supposed to call when the
> user does something?  If so, maybe we could improve that name.  Also, what
> does the boolean do?  (I have a personal vendetta against functions which
> take opaque boolean args, so maybe we can split this into two functions.)

It should notify the idle tracker when the user does something. The boolean says if the event should brighten the screen or not. This probably could be controlled by hard/soft policy, or managed by the apps.
 
> Do we need both screenEnabled and sleep()?  If I call sleep() while holding
> the appropriate wake lock, we'll only turn off the display, right?  Is there
> a way to programmatically wake up after calling sleep()?

We still need a way to know the exact screen state. Android uses alarm event to wake up the device programmatically.

> I'd prefer powerOff() and reboot() as separate functions.

Agree.

> With respect to the wake lock policy:
>   * Do "cpu" and "wakeup" always need to be "on"?  Is there another option?
>   * What's the difference between "screen: dim" and "screen: on"?  In both
> cases, I'm requesting that the screen not automatically turn off, right?

Someone(chris?) says "cpu: off" might be useful for eink device. The screen policy is requesting the minimum screen brightness.
 
> The big question here is: How much of our power management are we going to
> do in JS?  I suspect, for example, that we'll manage the screen's brightness
> from JS.  In that case, then we need an API for reading whether there are
> any wake locks held on the screen, and we probably don't need the |timeout|
> property.

I think most of the power management code can be done is JS. Only idle tracking, power on/off and wakelock that need HAL need native code.

> 
> In fact, the API that content can touch (requestWakeLock) should almost
> certainly be separate from the API that privileged code touches.
Comment 5 Justin Lebar (not reading bugmail) 2011-12-11 22:47:05 PST
We should split out the powerOff / reboot API and moving screen.enabled/brightness into two new bugs, since the wake lock API is pretty complicated.  You can file a separate bug on the wake lock API and mark all three as blocking this one, or you can file two new bugs and switch the lock API discussion to bug 697132, or you can dupe bug 697132 here...we just need one bug per issue, please.

> Yes. The timeout before screen locks.

Okay, so we're getting rid of this in favor of handling this in Gaia, right?

(re |userActivity|)
> The boolean says if the event should brighten the screen or not. This probably could be controlled 
> by hard/soft policy, or managed by the apps.

I don't think we need an API for notifying Gecko that a touch or button click happened.  Gecko generates these events itself.

It's conceivable that we'd want an API for the page to say "hey, something happened on the screen; treat it as though the user tapped or clicked."  For example, you're in a chat program and your buddy responds; you don't want the screen to immediately go dark.  But I think this API is a low priority compared to the rest here, and we should drop it for now.

> Someone(chris?) says "cpu: off" might be useful for eink device.

What does wakeup: off do?

And what's the difference between "screen: on" and "screen: dim"?

Also, I don't understand what the keyboard lock is supposed to do.

> I think most of the power management code can be done is JS.

Agreed.  Can you please post a new proposed API?  (It's actually two APIs; one for privileged code managing the power state, and the other for content.)
Comment 6 Kan-Ru Chen [:kanru] (UTC+8) 2011-12-11 23:42:44 PST
(In reply to Justin Lebar [:jlebar] from comment #5)
> We should split out the powerOff / reboot API and moving
> screen.enabled/brightness into two new bugs, since the wake lock API is
> pretty complicated.  You can file a separate bug on the wake lock API and
> mark all three as blocking this one, or you can file two new bugs and switch
> the lock API discussion to bug 697132, or you can dupe bug 697132 here...we
> just need one bug per issue, please.

Sure. Let's move the lock API discussion to bug 697132.

> > Yes. The timeout before screen locks.
> 
> Okay, so we're getting rid of this in favor of handling this in Gaia, right?

Yes.
 
> (re |userActivity|)
> I don't think we need an API for notifying Gecko that a touch or button
> click happened.  Gecko generates these events itself.
> 
> It's conceivable that we'd want an API for the page to say "hey, something
> happened on the screen; treat it as though the user tapped or clicked."  For
> example, you're in a chat program and your buddy responds; you don't want
> the screen to immediately go dark.  But I think this API is a low priority
> compared to the rest here, and we should drop it for now.

Agreed. And it can be done in Gaia.

> > Someone(chris?) says "cpu: off" might be useful for eink device.
> 
> What does wakeup: off do?

Quote the Android ACQUIRE_CAUSES_WAKEUP flag:
"Normal wake locks don't actually turn on the illumination. Instead, they cause the illumination to remain on once it turns on (e.g. from user activity). This flag will force the screen and/or keyboard to turn on immediately, when the WakeLock is acquired."

But since we have API for controlling screen brightness we might not need this.

> And what's the difference between "screen: on" and "screen: dim"?

The screen is turned on, but has different brightness. Again we might not need this, but it specifies the minimum requirement of an app. Each apps just set their requirement and Gaia can decide the final brightness.
 
> Also, I don't understand what the keyboard lock is supposed to do.

I think it's the keyboard backlight.

> > I think most of the power management code can be done is JS.
> 
> Agreed.  Can you please post a new proposed API?  (It's actually two APIs;
> one for privileged code managing the power state, and the other for content.)

For privileged code:

interface PowerManager {
  attribute double  screenBrightness;
  attribute boolean screenEnabled;

  void              sleep();
  void              powerOff();
  void              reboot();

  nsIDOMMozWakeLock requestWakeLock(in ACString topic);
};

We can implement content API on top of this.
Comment 7 Justin Lebar (not reading bugmail) 2011-12-12 04:21:12 PST
>   nsIDOMMozWakeLock requestWakeLock(in ACString topic);

Is this not the function exposed to content?  I expected we'd expose this to content (maybe privileged content only, but at least apps) and then have some API for our "chrome" to tell whether wake locks are held (see e.g. https://github.com/andreasgal/gaia/issues/167#issuecomment-3101666).

But we can move this discussion into other bugs.

Let me know if you need help with anything.
Comment 8 Kan-Ru Chen [:kanru] (UTC+8) 2011-12-12 20:18:51 PST
Created attachment 581165 [details] [diff] [review]
01
Comment 9 Kan-Ru Chen [:kanru] (UTC+8) 2011-12-12 20:19:24 PST
Created attachment 581166 [details] [diff] [review]
02
Comment 10 Kan-Ru Chen [:kanru] (UTC+8) 2011-12-12 20:19:49 PST
Created attachment 581167 [details] [diff] [review]
03
Comment 11 Kan-Ru Chen [:kanru] (UTC+8) 2011-12-12 20:20:11 PST
Created attachment 581168 [details] [diff] [review]
04
Comment 12 Kan-Ru Chen [:kanru] (UTC+8) 2011-12-12 20:20:33 PST
Created attachment 581169 [details] [diff] [review]
05
Comment 13 Kan-Ru Chen [:kanru] (UTC+8) 2011-12-12 20:20:56 PST
Created attachment 581170 [details] [diff] [review]
06
Comment 14 Kan-Ru Chen [:kanru] (UTC+8) 2011-12-12 20:29:23 PST
Sorry, this was for another bug.
Comment 15 Justin Lebar (not reading bugmail) 2011-12-12 20:37:29 PST
(btw, are you using hg bzexport [1]?  It makes exporting patch queues a lot easier.

[1] http://blog.mozilla.com/ted/2010/09/07/bzexport-a-mercurial-extension/)
Comment 16 Kan-Ru Chen [:kanru] (UTC+8) 2011-12-12 21:43:46 PST
(In reply to Justin Lebar [:jlebar] from comment #15)
> (btw, are you using hg bzexport [1]?  It makes exporting patch queues a lot
> easier.
> 
> [1] http://blog.mozilla.com/ted/2010/09/07/bzexport-a-mercurial-extension/)

I'm using Thinker's enhanced version :)

http://www.codemud.net/~thinker/en/GinGin_CGI.py/show_id_doc/2
Comment 17 Wesley Johnston (:wesj) 2012-07-19 09:22:57 PDT
(In reply to Kan-Ru Chen [:kanru] from comment #6)
> interface PowerManager {
>   attribute double  screenBrightness;
>   attribute boolean screenEnabled;
> 
>   void              sleep();
>   void              powerOff();
>   void              reboot();
> 
>   nsIDOMMozWakeLock requestWakeLock(in ACString topic);
> };
> 
> We can implement content API on top of this.

Sorry for the bugspam, but was looking for this for Fennec. For reference, we have an XPCOM component for some screen brightness stuff in Android (not exposed to content):
http://mxr.mozilla.org/mozilla-central/source/widget/nsIScreen.idl

It would be nice to deprecate that if we can.... I don't think its used by anyone (currently) except XUL Fennec. But since there's no alternative yet, I'll probably use it for things like fullscreen video.

Note You need to log in before you can comment on or make changes to this bug.