Closed Bug 708964 Opened 12 years ago Closed 12 years ago

Create API to manage the power usage of the device

Categories

(Core :: DOM: Core & HTML, defect)

All
Gonk (Firefox OS)
defect
Not set
normal

Tracking

()

RESOLVED FIXED

People

(Reporter: kanru, Unassigned)

References

Details

(Keywords: dev-doc-complete)

Attachments

(6 obsolete files)

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();
};
See Also: → 702256
See Also: → 697132
Depends on: 697132
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.
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.
(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.
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.)
(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.
>   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.
Depends on: 709585
Attached patch 01 (obsolete) — Splinter Review
Attachment #581165 - Flags: review?
Attached patch 02 (obsolete) — Splinter Review
Attachment #581166 - Flags: review?
Attached patch 03 (obsolete) — Splinter Review
Attachment #581167 - Flags: review?
Attached patch 04 (obsolete) — Splinter Review
Attachment #581168 - Flags: review?
Attached patch 05 (obsolete) — Splinter Review
Attachment #581169 - Flags: review?
Attached patch 06 (obsolete) — Splinter Review
Attachment #581170 - Flags: review?
Attachment #581165 - Attachment is obsolete: true
Attachment #581165 - Flags: review?
Attachment #581166 - Attachment is obsolete: true
Attachment #581166 - Flags: review?
Attachment #581167 - Attachment is obsolete: true
Attachment #581167 - Flags: review?
Attachment #581168 - Attachment is obsolete: true
Attachment #581168 - Flags: review?
Attachment #581169 - Attachment is obsolete: true
Attachment #581169 - Flags: review?
Attachment #581170 - Attachment is obsolete: true
Attachment #581170 - Flags: review?
Sorry, this was for another bug.
(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/)
(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
Depends on: 710135
Depends on: 739913
Blocks: webapi
(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.
Status: NEW → RESOLVED
Closed: 12 years ago
Resolution: --- → FIXED
Component: DOM → DOM: Core & HTML
You need to log in before you can comment on or make changes to this bug.