Jam-detection: Add new debug property to get the history bitmap (#1033)

This commit adds support to get history-bitmap value from
jam-detection module. It also adds a corresponding spinel property
and a get handler for the new property in `NcpBase`.

The history bitmap provides information about current state of jamming
detection module for monitoring/debugging purpose. It returns a 64-bit
value where each bit corresponds to one second interval starting with
bit 0 for the most recent interval and bit 63 for the oldest intervals
(63 sec earlier). The bit is set to 1 if the jamming detection module
observed/detected high signal level during the corresponding one second
interval.

doc/spinel-protocol-src/spinel-feature-jam-detect.md

@@ -81,3 +81,20 @@ the detection window where the RSSI must be above
 
 The behavior of the jamming detection feature when `PROP_JAM_DETECT_BUSY`
 is larger than `PROP_JAM_DETECT_WINDOW` is undefined.
+
+### PROP 4613: SPINEL_PROP_JAM_DETECT_HISTORY_BITMAP
+
+* Type: Read-Only
+* Packed-Encoding: `LL`
+* Default Value: Implementation-specific
+* RECOMMENDED for `CAP_JAM_DETECT`
+
+This value provides information about current state of jamming detection
+module for monitoring/debugging purpose. It returns a 64-bit value where
+each bit corresponds to one second interval starting with bit 0 for the
+most recent interval and bit 63 for the oldest intervals (63 sec earlier).
+The bit is set to 1 if the jamming detection module observed/detected
+high signal level during the corresponding one second interval.
+The value is read-only and is encoded as two `L` (uint32) values in
+little-endian format (first `L` (uint32) value gives the lower bits
+corresponding to more recent history).

include/openthread-jam-detection.h

@@ -168,6 +168,22 @@ bool otIsJamDetectionEnabled(otInstance *aInstance);
  */
 bool otGetJamDetectionState(otInstance *aInstance);
 
+/**
+ * Get the current history bitmap.
+ *
+ * This value provides information about current state of jamming detection
+ * module for monitoring/debugging purpose. It returns a 64-bit value where
+ * each bit corresponds to one second interval starting with bit 0 for the
+ * most recent interval and bit 63 for the oldest intervals (63 sec earlier).
+ * The bit is set to 1 if the jamming detection module observed/detected
+ * high signal level during the corresponding one second interval.
+ *
+ * @param[in]  aInstance            A pointer to an OpenThread instance.
+ *
+ * @returns The current history bitmap.
+ */
+uint64_t otGetJamDetectionHistoryBitmap(otInstance *aInstance);
+
 /**
  * @}
  *

src/core/openthread.cpp

@@ -980,6 +980,11 @@ bool otGetJamDetectionState(otInstance *aInstance)
 {
     return aInstance->mThreadNetif.GetJamDetector().GetState();
 }
+
+uint64_t otGetJamDetectionHistoryBitmap(otInstance *aInstance)
+{
+    return aInstance->mThreadNetif.GetJamDetector().GetHistoryBitmap();
+}
 #endif // OPENTHREAD_ENABLE_JAM_DETECTION
 
 bool otIsIp6AddressEqual(const otIp6Address *a, const otIp6Address *b)

src/core/utils/jam_detector.hpp

@@ -163,6 +163,20 @@ public:
      */
     uint8_t GetBusyPeriod(void) const { return mBusyPeriod; }
 
+    /**
+     * Get the current history bitmap.
+     *
+     * This value provides information about current state of jamming detection
+     * module for monitoring/debugging purpose. It provides a 64-bit value where
+     * each bit corresponds to one second interval starting with bit 0 for the
+     * most recent interval and bit 63 for the oldest intervals (63 earlier).
+     * The bit is set to 1 if the jamming detection module observed/detected
+     * high signal level during the corresponding one second interval.
+     *
+     * @returns The current history bitmap.
+     */
+    uint64_t GetHistoryBitmap(void) const { return mHistoryBitmap; }
+
 private:
     static void HandleTimer(void *aContext);
     void HandleTimer(void);

src/ncp/ncp_base.cpp

@@ -169,6 +169,7 @@ const NcpBase::GetPropertyHandlerEntry NcpBase::mGetPropertyHandlerTable[] =
     { SPINEL_PROP_JAM_DETECT_RSSI_THRESHOLD, &NcpBase::GetPropertyHandler_JAM_DETECT_RSSI_THRESHOLD },
     { SPINEL_PROP_JAM_DETECT_WINDOW, &NcpBase::GetPropertyHandler_JAM_DETECT_WINDOW },
     { SPINEL_PROP_JAM_DETECT_BUSY, &NcpBase::GetPropertyHandler_JAM_DETECT_BUSY },
+    { SPINEL_PROP_JAM_DETECT_HISTORY_BITMAP, &NcpBase::GetPropertyHandler_JAM_DETECT_HISTORY_BITMAP },
 #endif
 
     { SPINEL_PROP_CNTR_TX_PKT_TOTAL, &NcpBase::GetPropertyHandler_MAC_CNTR },
@@ -2485,6 +2486,20 @@ ThreadError NcpBase::GetPropertyHandler_JAM_DETECT_BUSY(uint8_t header, spinel_p
            );
 }
 
+ThreadError NcpBase::GetPropertyHandler_JAM_DETECT_HISTORY_BITMAP(uint8_t header, spinel_prop_key_t key)
+{
+    uint64_t historyBitmap = otGetJamDetectionHistoryBitmap(mInstance);
+
+    return SendPropertyUpdate(
+               header,
+               SPINEL_CMD_PROP_VALUE_IS,
+               key,
+               SPINEL_DATATYPE_UINT32_S SPINEL_DATATYPE_UINT32_S,
+               static_cast<uint32_t>(historyBitmap & 0xffffffff),
+               static_cast<uint32_t>(historyBitmap >> 32)
+           );
+}
+
 #endif // OPENTHREAD_ENABLE_JAM_DETECTION
 
 ThreadError NcpBase::GetPropertyHandler_MAC_CNTR(uint8_t header, spinel_prop_key_t key)

src/ncp/ncp_base.hpp

@@ -359,6 +359,7 @@ private:
     ThreadError GetPropertyHandler_JAM_DETECT_RSSI_THRESHOLD(uint8_t header, spinel_prop_key_t key);
     ThreadError GetPropertyHandler_JAM_DETECT_WINDOW(uint8_t header, spinel_prop_key_t key);
     ThreadError GetPropertyHandler_JAM_DETECT_BUSY(uint8_t header, spinel_prop_key_t key);
+    ThreadError GetPropertyHandler_JAM_DETECT_HISTORY_BITMAP(uint8_t header, spinel_prop_key_t key);
 #endif
 
 #if OPENTHREAD_ENABLE_LEGACY

src/ncp/spinel.h

@@ -543,6 +543,23 @@ typedef enum
      */
     SPINEL_PROP_JAM_DETECT_BUSY         = SPINEL_PROP_PHY_EXT__BEGIN + 4,
 
+    /// Jamming detection history bitmap (for debugging)
+    /** Format: `LL` (read-only)
+     *
+     * This value provides information about current state of jamming detection
+     * module for monitoring/debugging purpose. It returns a 64-bit value where
+     * each bit corresponds to one second interval starting with bit 0 for the
+     * most recent interval and bit 63 for the oldest intervals (63 sec earlier).
+     * The bit is set to 1 if the jamming detection module observed/detected
+     * high signal level during the corresponding one second interval.
+     *
+     * The value is read-only and is encoded as two uint32 values in
+     * little-endian format (first uint32 gives the lower bits corresponding to
+     * more recent history).
+     */
+    SPINEL_PROP_JAM_DETECT_HISTORY_BITMAP
+                                        = SPINEL_PROP_PHY_EXT__BEGIN + 5,
+
     SPINEL_PROP_PHY_EXT__END            = 0x1300,
 
     SPINEL_PROP_MAC__BEGIN             = 0x30,