From 08e52e55a59cf658262aa591e26c7bf2ec34751b Mon Sep 17 00:00:00 2001 From: Robert Quattlebaum Date: Fri, 12 May 2017 10:02:53 -0700 Subject: [PATCH] spinel: Introduce PROP_HOST_POWER_STATE (#1722) Introduces a new core property (`PROP_HOST_POWER_STATE`) which is used by the host to inform the NCP of the power state of the *host*. The NCP can then use this state to determine which properties need asynchronous updates. The states are defined in similar terms to those used for the `PROP_POWER_STATE` property. --- doc/spinel-protocol-src/spinel-prop-core.md | 67 ++++++++++++++++++++- 1 file changed, 66 insertions(+), 1 deletion(-) diff --git a/doc/spinel-protocol-src/spinel-prop-core.md b/doc/spinel-protocol-src/spinel-prop-core.md index 9b9bb0591..c52ca98f7 100644 --- a/doc/spinel-protocol-src/spinel-prop-core.md +++ b/doc/spinel-protocol-src/spinel-prop-core.md @@ -209,9 +209,15 @@ Defined values are: * 4: `POWER_STATE_ONLINE`: NCP is fully powered. (e.g. "Parent" node) + + ### PROP 8: PROP_HWADDR {#prop-hwaddr} -* Type: Read-Only* +* Type: Read-Only\* * Packed-Encoding: `E` Octets: | 8 @@ -242,6 +248,65 @@ Unlike most other properties, setting this property to true when the value of the property is already true **MUST** fail with a last status of `STATUS_ALREADY`. +### PROP 10: PROP_HOST_POWER_STATE {#prop-host-power-state} + +* Type: Read-Write +* Packed-Encoding: `C` +* Default value: 4 + +Octets: | 1 +--------|------------------ +Fields: | `HOST_POWER_STATE` + +Describes the current power state of the *host*. This property is used +by the host to inform the NCP when it has changed power states. The +NCP can then use this state to determine which properties need +asynchronous updates. Enumeration is encoded as a single unsigned +byte. These states are defined in similar terms to `PROP_POWER_STATE` +((#prop-power-state)). + +Defined values are: + +* 0: `HOST_POWER_STATE_OFFLINE`: Host is physically powered off and + cannot be woken by the NCP. All asynchronous commands are + squelched. +* 1: `HOST_POWER_STATE_DEEP_SLEEP`: The host is in a low power state + where it can be woken by the NCP but will potentially require more + than two seconds to become fully responsive. The NCP **MUST** + avoid sending unnecessary property updates, such as child table + updates or non-critical messages on the debug stream. If the NCP + needs to wake the host for traffic, the NCP **MUST** first take + action to wake the host. Once the NCP signals to the host that it + should wake up, the NCP **MUST** wait for some activity from the + host (indicating that it is fully awake) before sending frames. +* 2: **RESERVED**. This value **MUST NOT** be set by the host. If + received by the NCP, the NCP **SHOULD** consider this as a synonym + of `HOST_POWER_STATE_DEEP_SLEEP`. +* 3: `HOST_POWER_STATE_LOW_POWER`: The host is in a low power state + where it can be immediately woken by the NCP. The NCP **SHOULD** + avoid sending unnecessary property updates, such as child table + updates or non-critical messages on the debug stream. +* 4: `HOST_POWER_STATE_ONLINE`: The host is awake and responsive. No + special filtering is performed by the NCP on asynchronous updates. +* All other values are **RESERVED**. They MUST NOT be set by the + host. If received by the NCP, the NCP **SHOULD** consider the value as + a synonym of `HOST_POWER_STATE_LOW_POWER`. + + + +After setting this power state, any further commands from the host to +the NCP will cause `HOST_POWER_STATE` to automatically revert to +`HOST_POWER_STATE_ONLINE`. + +When the host is entering a low-power state, it should wait for the +response from the NCP acknowledging the command (with `CMD_VALUE_IS`). +Once that acknowledgement is received the host may enter the low-power +state. + ## Stream Properties {#prop-stream} ### PROP 112: PROP_STREAM_DEBUG {#prop-stream-debug}