--- /dev/null
+## Power Management
+
+### Overview
+
+Power management (PM) in bluedroid is an event-driven state machine, tickled by
+various `bta/sys` events via a callback. The actual state switching calls are
+handled by the BTM HCI interfacing code, with results being posted back to the
+PM code via the BTA workqueue thread.
+
+Power states are managed per-device, per-profile, so every incoming event
+includes a profile ID, app ID, and a `BD_ADDR`.
+
+The events fired to drive the state machine at the time of this writing are:
+
+ - `BTA_SYS_CONN_OPEN`
+ - `BTA_SYS_CONN_CLOSE`
+ - `BTA_SYS_CONN_IDLE`
+ - `BTA_SYS_CONN_BUSY`
+ - `BTA_SYS_APP_OPEN`
+ - `BTA_SYS_APP_CLOSE`
+ - `BTA_SYS_SCO_OPEN`
+ - `BTA_SYS_SCO_CLOSE`
+
+Each of these correspond to a function name in `bta/sys/bta_sys_conn.c`, which
+are called by each profile definition in `bta/$PROFILE`.
+
+The PM code makes calls into the BTM module to set various power
+states. Responses are handled in an asynchronous fashion, primarily via the
+callbacks `bta_dm_pm_cback` and `bta_dm_pm_timer_cback`. Responses are handled
+through the BTA workqueue thread and the `bta_dm_pm_btm_status` function. Since
+we might possibly get into a bad state where we never hear back from the
+controller, timers are used to post messages to the BTA workqueue thread as
+well, which filters down through the same status function.
+
+Overall power states are managed *per device*, not per connection, but the power
+policy is determined by the greatest allowable power action defined across all
+currently known connections to a given device. Thus, if RFCOMM specifies that
+it's willing to go to into SNIFF and specifies that as an action, and say, a PAN
+connection is up which specifies it is willing to go into SNIFF, but its action
+states it wants ACTIVE, the power management code will change to ACTIVE.
+
+### Power management tables
+
+The tables that determine which power levels are acceptable for which profiles
+and what actions to take for the above events are defined in the
+`bta/dm/bta_dm_cfg.c` file, as `bta_dm_pm_cfg`, `bta_dm_pm_spec`, and
+`bta_dm_ssr_spec`.
+
+During a lookup attempt, the code iterates over the `bta_dm_pm_cfg` array,
+looking for a match between the profile and app IDs. When it finds one, it uses
+the `spec_idx` field to index into `bta_dm_pm_spec` array to determine which
+power modes are acceptable and what actions to take for each event.
+
+The action constants are defined in `bta_api.h` and are defined as a series of
+hex bitfields. The actual actions taken are determined by the
+`bta_dm_pm_set_mode` function, but a few of the actions listed deserve some
+additional description:
+
+ - `BTA_DM_PM_NO_ACTION` is effectively a no-op and has a value of zero, so any
+ other profile will override this.
+ - `BTA_DM_PM_NO_PREF` overrides `BTA_DM_PM_NO_ACTION` and if selected as the
+ action that `bta_dm_pm_set_mode` will take, the connection will be removed
+ from `bta_dm_conn_srvcs` and no longer be considered for power management
+ decisions.
+ - `BTA_DM_PM_SNIFF` through `BTA_DM_PM_SNIFF4` are special, in that each
+ level specifies a set of parameters for the SNIFF mode which relate to the
+ min and max intervals, the number of attempts and the timeout. The overall
+ action is still the same, however -- SNIFF mode is attempted. There are
+ definitions available up to SNIFF7, but actual SSR values are only defined
+ up to SNIFF4. Params are defined in `bta_dm_ssr_spec`.
+ - `BTA_DM_PM_ACTIVE` is full-on power.
+ - `BTA_DM_PM_RETRY` has the same effect as `BTA_DM_PM_NO_ACTION`, except a
+ timeout is possible to be set, which effectively allows a power operation to
+ be "retried".
+
+### Initialization
+
+`bta_dm_pm.c`'s `bta_dm_init_pm` function calls out to register
+`bta_dm_pm_cback` with the bta sys module for incoming power management events,
+and also registers `bta_dm_pm_btm_cback` with the btm module to handle responses
+and timeouts of HCI requests (via `bta_dm_pm_btm_status`).
+
+At this point, the power managment code is basically done until the first set of
+events come in through `bta_dm_pm_cback`.
+
+Throughout the `bta_dm_pm.c` file, connections whose power management states are
+managed are tracked in a global array called `bta_dm_conn_srvcs`. Unfortunately,
+while this variable is declared as an extern in the `bta_dm_int.h` file, it only
+seems to be used in the `bta_dm_act.c` file, and only for reinitialization.
+
+### Event flow
+
+#### Events fired from SYS
+
+ 1. An event is fired from one of the methods mentioned above in
+ `bta/sys/bta_sys_conn.c`
+ 2. The `bta_dm_pm_cback` function is called.
+ - The power mode config is looked up in the `bta_dm_pm_cfg` table. If none
+ are found for the given profile ID and app ID, the function simply
+ returns with no action taken.
+ - If any timers were set for the given `BD_ADDR`, they are stopped.
+ - The SSR params for the CONN_OPEN event are looked up.
+ - The power spec state table (`bta_dm_pm_spec`) is checked to see if
+ there's no action to be performed (`BTA_DM_PM_NO_ACTION`), and if so,
+ returns with no action taken.
+ - `bta_dm_conn_srvcs` is consulted to ensure there's an entry for this
+ connection if it's supposed to be managed according to the power spec
+ state tables. If the spec specifies `BTA_DM_PM_NO_PREF`, then any
+ existing entry in this list is removed, otherwise one is added/updated
+ with the state given to the function.
+ 3. `bta_dm_pm_cback` checks to see if the `bta_dm_ssr_spec` specifies SSR
+ adjustments are to be made, and if so, `bta_dm_pm_ssr` is called with the
+ peer `BD_ADDR`.
+ - `bta_dm_pm_ssr` iterates the managed services array to find all connected
+ services for the given `BD_ADDR`, then looks up the ssr values from the
+ `bta_dm_ssr_spec` tables, looking for the smallest max latency to use.
+ - `bta_dm_pm_ssr` calls `BTM_SetSsrParams` to actually send along the SSR
+ params to the bluetooth chip.
+ 4. `bta_dm_pm_cback` calls `bta_dm_pm_set_mode` with the peer address and the
+ `timed_out` parameter set to `false`.
+ - For each managed connection, `bta_dm_pm_set_mode` grabs
+ both actions specified for the profile in the `bta_dm_pm_spec` tables. If
+ the first power management action didn't timeout (or was never attempted,
+ according to the `tBTA_DM_PEER_DEVICE` `pm_mode_failed` and
+ `pm_mode_attempted` fields), its timeout and mode are used. Otherwise,
+ the same check is done against the second action and it is used
+ instead. If both actions have been attempted, then the action is set to
+ `BTA_DM_PM_NO_ACTION`. Only the highest power mode action is chosen from
+ all connected profiles.
+ - If the chosen action is `BTA_DM_PM_PARK` or `BTA_DM_PM_SNIFF` but the
+ profile doesn't allow it, this function takes no action.
+ - If a timeout is specified in the power spec table, then an unused timer
+ in `bta_dm_cb.pm_timer` is started.
+ - If the action chosen is `BTA_DM_PM_PARK`, `bta_dm_pm_park` is called,
+ which calls `BTM_ReadPowerMode` and `BTM_SetPowerMode` to make an HCI
+ request to enable PARK for the given peer and connection.
+ - If the action chosen is `BTA_DM_PM_SNIFF`, the peer device's link policy
+ is checked to see if it's allowed. If so, then `bta_dm_pm_sniff` is
+ called, which makes various calls to `BTM_ReadLocalFeatures`,
+ `BTM_ReadRemoteFeatures` and `BTM_SetPowerMode` to ensure SNIFF mode is
+ enabled.
+ - If the action chosen is `BTA_DM_PM_ACTIVE`, a call to `bta_dm_pm_active`
+ is made, which calls `BTM_SetPowerMode` to set the link into ACTIVE
+ mode.
+
+At this point, if one of the timers in `bta_dm_cb.pm_timer` times out, a call is
+made through the BTA workqueue thread to `bta_dm_pm_btm_cback`, which then
+triggers `bta_dm_pm_btm_status`, with the timeout field set to TRUE. HCI
+responses are also fired as messages through the BTA workqueue thread, which are
+handled again, through `bta_dm_pm_btm_status`.
+
+#### Events fired through BTM
+
+Essentially these messages eventually go through the same functions as events
+fired from the SYS side of things, except from the initial path they take:
+
+ 1. An event is fired from a callback in BTM to `bta_dm_pm_btm_cback`.
+ 2. `bta_dm_pm_btm_cback` packages up the given parameters into a
+ `tBTA_DM_PM_BTM_STATUS` struct and posts it to the BTA workqueue thread via
+ `bta_sys_sendmsg`, with the event header set to
+ `BTA_DM_PM_BTM_STATUS_EVT`.
+ 3. This is eventually routed to the `bta_dm_pm_btm_status` function.
+ **Determine if this is running on the workqueue thread or not**
+ - The message `status` passed in is actually the current status of the
+ device.
+ - If the status is `BTM_PM_STS_ACTIVE` (still in the ACTIVE power mode),
+ checks the HCI status code:
+ - If that's non-zero and a PARK or SNIFF mode change was attempted,
+ `bta_dm_pm_btm_status` stops any timers started for the device in
+ `bta_dm_pm_set_mode`, clears some status bits in the peer device
+ structure, and then calls back into `bta_dm_pm_set_mode` with the peer
+ device address and timeout set to FALSE.
+ - If the status is zero, and if the peer device `tBTA_DM_PEER_DEVICE`
+ `prev_low` field is set, calls `bta_dm_pm_ssr` to re-send SSR params,
+ stops all timers for the device, and then re-calls `bta_dm_pm_set_mode`
+ with timeout set to FALSE to re-attempt with a second action (if the
+ previous PARK or SNIFF failed, otherwise it'll re-attempt the first
+ action).
+ - If the status is `BTM_PM_STS_PARK` or `BTM_PM_STS_HOLD`, saves the
+ previous low power mode in the peer device's `prev_low` field.
+ - If the status is `BTM_PM_STS_SSR`, simply clears or sets the device
+ `info` field's `BTA_DM_DI_USE_SSR` bit, depending on the value of
+ `tBTA_DM_MSG.value`, which determines if the device can handle SSR.
+ - If the status is `BTM_PM_STS_SNIFF` and the info field has the
+ `BTA_DM_DI_SET_SNIFF` bit set, then `BTA_DM_DI_INT_SNIFF` is set,
+ otherwise `BTA_DM_DI_ACP_SNIFF` is set.
+ - If `BTA_PM_STS_ERROR`, the `BTA_DM_DI_SET_SNIFF` bit is cleared in the
+ device info field.
+
+At this point, either the method simply returns, or has called back into
+`bta_dm_pm_set_mode`, in which case the usual flow takes over.
+
+#### Events fired from timers
+
+Timers are used exclusively for handling HCI command timeouts, and filter
+through to a call to `bta_dm_pm_set_mode`:
+
+ 1. A timer expires, and calls `bta_dm_pm_timer_cback`.
+ 2. `bta_dm_pm_timer_cback` clears the use flag on the timer that fired, and
+ sends off an event to the BTA workqueue thread.
+ 3. The event eventually fires off a call to `bta_dm_pm_timer`, which just
+ calls `bta_dm_pm_set_mode` with timeout set to `TRUE`.
OSDN Git Service
