[ncp] Add new spinel property MAC_DATA_POLL_PERIOD and its get/set handlers (#1952)

The spinel-protocol draft is also updated.

doc/spinel-protocol-src/spinel-prop-mac.md

@@ -122,6 +122,22 @@ per scanned channel with following format:
 * `C`: Channel
 * `c`: RSSI (in dBm)
 
+### PROP 58: PROP_MAC_DATA_POLL_PERIOD {#prop-mac-data-poll-period
+* Type: Read-Write
+* Packed-Encoding: `L`
+
+The (user-specified) data poll (802.15.4 MAC Data Request) period
+in milliseconds. Value zero means there is no user-specified
+poll period, and the network stack determines the maximum period
+based on the MLE Child Timeout.
+
+If the value is non-zero, it specifies the maximum period between
+data poll transmissions. Note that the network stack may send data
+request transmissions more frequently when expecting a control-message
+(e.g., when waiting for an MLE Child ID Response).
+
+This property is only present on NCPs which implement 802.15.4.
+
 ### PROP 4864: PROP_MAC_WHITELIST  {#prop-mac-whitelist}
 * Type: Read-Write
 * Packed-Encoding: `A(T(Ec))`

include/openthread/link.h

@@ -277,7 +277,7 @@ OTAPI otError OTCALL otLinkSetPanId(otInstance *aInstance, otPanId aPanId);
  *
  * @param[in]  aInstance A pointer to an OpenThread instance.
  *
- * @returns  The data poll period of sleepy end device.
+ * @returns  The data poll period of sleepy end device in milliseconds.
  *
  * @sa otLinkSetPollPeriod
  */
@@ -290,7 +290,7 @@ OTAPI uint32_t OTCALL otLinkGetPollPeriod(otInstance *aInstance);
  *       otSetChildTimeout() shall be called.
  *
  * @param[in]  aInstance    A pointer to an OpenThread instance.
- * @param[in]  aPollPeriod  data poll period.
+ * @param[in]  aPollPeriod  data poll period in milliseconds.
  *
  * @sa otLinkGetPollPeriod
  */

src/ncp/ncp_base.cpp

@@ -138,6 +138,7 @@ const NcpBase::GetPropertyHandlerEntry NcpBase::mGetPropertyHandlerTable[] =
     NCP_GET_PROP_HANDLER_ENTRY(MAC_RAW_STREAM_ENABLED),
     NCP_GET_PROP_HANDLER_ENTRY(MAC_PROMISCUOUS_MODE),
     NCP_GET_PROP_HANDLER_ENTRY(MAC_EXTENDED_ADDR),
+    NCP_GET_PROP_HANDLER_ENTRY(MAC_DATA_POLL_PERIOD),
     NCP_GET_PROP_HANDLER_ENTRY(NET_SAVED),
     NCP_GET_PROP_HANDLER_ENTRY(NET_IF_UP),
     NCP_GET_PROP_HANDLER_ENTRY(NET_STACK_UP),
@@ -287,6 +288,7 @@ const NcpBase::SetPropertyHandlerEntry NcpBase::mSetPropertyHandlerTable[] =
     NCP_SET_PROP_HANDLER_ENTRY(MAC_SCAN_PERIOD),
     NCP_SET_PROP_HANDLER_ENTRY(MAC_15_4_PANID),
     NCP_SET_PROP_HANDLER_ENTRY(MAC_15_4_LADDR),
+    NCP_SET_PROP_HANDLER_ENTRY(MAC_DATA_POLL_PERIOD),
     NCP_SET_PROP_HANDLER_ENTRY(MAC_RAW_STREAM_ENABLED),
     NCP_SET_PROP_HANDLER_ENTRY(NET_IF_UP),
     NCP_SET_PROP_HANDLER_ENTRY(NET_STACK_UP),
@@ -2576,6 +2578,17 @@ otError NcpBase::GetPropertyHandler_MAC_EXTENDED_ADDR(uint8_t aHeader, spinel_pr
            );
 }
 
+otError NcpBase::GetPropertyHandler_MAC_DATA_POLL_PERIOD(uint8_t aHeader, spinel_prop_key_t aKey)
+{
+    return SendPropertyUpdate(
+               aHeader,
+               SPINEL_CMD_PROP_VALUE_IS,
+               aKey,
+               SPINEL_DATATYPE_UINT32_S,
+               otLinkGetPollPeriod(mInstance)
+           );
+}
+
 otError NcpBase::GetPropertyHandler_MAC_RAW_STREAM_ENABLED(uint8_t aHeader, spinel_prop_key_t aKey)
 {
     return SendPropertyUpdate(
@@ -4710,6 +4723,28 @@ exit:
     return SendSetPropertyResponse(aHeader, aKey, error);
 }
 
+otError NcpBase::SetPropertyHandler_MAC_DATA_POLL_PERIOD(uint8_t aHeader, spinel_prop_key_t aKey,
+                                                         const uint8_t *aValuePtr, uint16_t aValueLen)
+{
+    uint32_t pollPeriod;
+    spinel_ssize_t parsedLength;
+    otError error = OT_ERROR_NONE;
+
+    parsedLength = spinel_datatype_unpack(
+                       aValuePtr,
+                       aValueLen,
+                       SPINEL_DATATYPE_UINT32_S,
+                       &pollPeriod
+                   );
+
+    VerifyOrExit(parsedLength > 0, error = OT_ERROR_PARSE);
+
+    otLinkSetPollPeriod(mInstance, pollPeriod);
+
+exit:
+    return SendSetPropertyResponse(aHeader, aKey, error);
+}
+
 otError NcpBase::SetPropertyHandler_MAC_RAW_STREAM_ENABLED(uint8_t aHeader, spinel_prop_key_t aKey,
                                                            const uint8_t *aValuePtr, uint16_t aValueLen)
 {

src/ncp/ncp_base.hpp

@@ -355,6 +355,7 @@ private:
     NCP_GET_PROP_HANDLER(MAC_15_4_SADDR);
     NCP_GET_PROP_HANDLER(MAC_RAW_STREAM_ENABLED);
     NCP_GET_PROP_HANDLER(MAC_EXTENDED_ADDR);
+    NCP_GET_PROP_HANDLER(MAC_DATA_POLL_PERIOD);
     NCP_GET_PROP_HANDLER(NET_SAVED);
     NCP_GET_PROP_HANDLER(NET_IF_UP);
     NCP_GET_PROP_HANDLER(NET_STACK_UP);
@@ -451,6 +452,7 @@ private:
     NCP_SET_PROP_HANDLER(MAC_SCAN_STATE);
     NCP_SET_PROP_HANDLER(MAC_15_4_PANID);
     NCP_SET_PROP_HANDLER(MAC_15_4_LADDR);
+    NCP_SET_PROP_HANDLER(MAC_DATA_POLL_PERIOD);
     NCP_SET_PROP_HANDLER(MAC_RAW_STREAM_ENABLED);
 #if OPENTHREAD_ENABLE_RAW_LINK_API
     NCP_SET_PROP_HANDLER(MAC_15_4_SADDR);

src/ncp/spinel.c

@@ -1068,6 +1068,10 @@ spinel_prop_key_to_cstr(spinel_prop_key_t prop_key)
         ret = "PROP_MAC_ENERGY_SCAN_RESULT";
         break;
 
+    case SPINEL_PROP_MAC_DATA_POLL_PERIOD:
+        ret = "PROP_MAC_DATA_POLL_PERIOD";
+        break;
+
     case SPINEL_PROP_MAC_WHITELIST:
         ret = "PROP_MAC_WHITELIST";
         break;

src/ncp/spinel.h

@@ -636,16 +636,17 @@ typedef enum
     SPINEL_PROP_PHY_EXT__END            = 0x1300,
 
     SPINEL_PROP_MAC__BEGIN              = 0x30,
-    SPINEL_PROP_MAC_SCAN_STATE          = SPINEL_PROP_MAC__BEGIN + 0, ///< [C]
+    SPINEL_PROP_MAC_SCAN_STATE          = SPINEL_PROP_MAC__BEGIN + 0,  ///< [C]
-    SPINEL_PROP_MAC_SCAN_MASK           = SPINEL_PROP_MAC__BEGIN + 1, ///< [A(C)]
+    SPINEL_PROP_MAC_SCAN_MASK           = SPINEL_PROP_MAC__BEGIN + 1,  ///< [A(C)]
-    SPINEL_PROP_MAC_SCAN_PERIOD         = SPINEL_PROP_MAC__BEGIN + 2, ///< ms-per-channel [S]
+    SPINEL_PROP_MAC_SCAN_PERIOD         = SPINEL_PROP_MAC__BEGIN + 2,  ///< ms-per-channel [S]
-    SPINEL_PROP_MAC_SCAN_BEACON         = SPINEL_PROP_MAC__BEGIN + 3, ///< chan,rssi,mac_data,net_data [CcdD]
+    SPINEL_PROP_MAC_SCAN_BEACON         = SPINEL_PROP_MAC__BEGIN + 3,  ///< chan,rssi,mac_data,net_data [CcdD]
-    SPINEL_PROP_MAC_15_4_LADDR          = SPINEL_PROP_MAC__BEGIN + 4, ///< [E]
+    SPINEL_PROP_MAC_15_4_LADDR          = SPINEL_PROP_MAC__BEGIN + 4,  ///< [E]
-    SPINEL_PROP_MAC_15_4_SADDR          = SPINEL_PROP_MAC__BEGIN + 5, ///< [S]
+    SPINEL_PROP_MAC_15_4_SADDR          = SPINEL_PROP_MAC__BEGIN + 5,  ///< [S]
-    SPINEL_PROP_MAC_15_4_PANID          = SPINEL_PROP_MAC__BEGIN + 6, ///< [S]
+    SPINEL_PROP_MAC_15_4_PANID          = SPINEL_PROP_MAC__BEGIN + 6,  ///< [S]
-    SPINEL_PROP_MAC_RAW_STREAM_ENABLED  = SPINEL_PROP_MAC__BEGIN + 7, ///< [C]
+    SPINEL_PROP_MAC_RAW_STREAM_ENABLED  = SPINEL_PROP_MAC__BEGIN + 7,  ///< [C]
-    SPINEL_PROP_MAC_PROMISCUOUS_MODE    = SPINEL_PROP_MAC__BEGIN + 8, ///< [C]
+    SPINEL_PROP_MAC_PROMISCUOUS_MODE    = SPINEL_PROP_MAC__BEGIN + 8,  ///< [C]
-    SPINEL_PROP_MAC_ENERGY_SCAN_RESULT  = SPINEL_PROP_MAC__BEGIN + 9, ///< chan,maxRssi [Cc]
+    SPINEL_PROP_MAC_ENERGY_SCAN_RESULT  = SPINEL_PROP_MAC__BEGIN + 9,  ///< chan,maxRssi [Cc]
+    SPINEL_PROP_MAC_DATA_POLL_PERIOD    = SPINEL_PROP_MAC__BEGIN + 10, ///< pollPeriod (in ms) [L]
     SPINEL_PROP_MAC__END                = 0x40,
 
     SPINEL_PROP_MAC_EXT__BEGIN          = 0x1300,