docs/concepts/power/intro/README.md

# Audience

This document is aimed at someone who wants to start using power framework and
has little or no prior exposure. It may be suitable as a reference for people
with prior exposure to power framework.


## Goals of power framework

Why have a power framework? The goal is to save power. To achieve this goal,
power framework provides mechanisms for coordination and debuggability related
to power. By coordination we mean a mechanism for components in Fuchsia to order
their actions so they can properly (ie. power efficiently) operate the system.
By debuggability we mean the ability to understand the state of the system with
respect to power, how that system changes over time, and what is causing the
state changes.

The goal of the power framework is not to save power via some clever mechanism
of scheduling or resource management. Rather it manages the resources as
directed and gives the system's developers the tools needed to understand and
optimize power usage.


## Coordination

Accomplishing certain work in the system requires the availability of certain
resources. These resources should remain available until the work completes.
Power framework provides a standardized coordination mechanism to manage
resources.

For example, consider a program that wants to download a file. Let us say that
the program requires two things to download the file: the CPU and the network
protocol stack. The network protocol stack in turn requires the CPU and the
network driver.

If the application, netstack, CPU manager, and network driver integrate with
power framework, then power framework can coordinate telling the owners of
resources when the resources should or should not be available. In our example,
this means that the application can request the system be able to download
something. Power framework will then send messages to resource owners in the
proper order to prepare the system, sending messages to the owner of various
power elements, first the CPU then the network driver then network protocol
stack to prepare and finally to the application that the system is ready. Once
the download is complete the application can withdraw its request that the
system be able to download something and power framework will coordinate turning
down unused resources.


## Debuggability

The power framework, as the coordinator of system state changes, has a huge
amount of information about the state of the system. It makes this information
available about what state a resource is told to be in and state of the resource
reported by its owner through things like Inspect. We can then build tools to
analyze this treasure trove, understand the system, and improve its function.