Revision 561:613dbbdeed27, committed 2016-01-11

Comitter:

vcoubard

Date:

Mon Jan 11 10:19:15 2016 +0000

Parent:

560:f6e25408c913

Child:

562:0d32ae12429e

Commit message:

Synchronized with git rev 7bf81e7e
Author: Andres Amaya Garcia
Improve shutdown to clear BLE API and not just SD

Improve the shutdown functionality, such that a call to ble.shutdown() from
the user application clears the API and nRF5x state and NOT only the
SoftDevice. To achieve this the following changes are introduced:

* Add a protected member cleanup() to nRF5xGap, nRF5xGattClient,
nRF5xGattServer, nRF5xSecurityManager and nRF5xServiceDiscovery.
* Modify the shutdown() implementation in nRF5xn such that it also calls the
static member shutdown() exposed by the BLE API in Gap.h, SecurityManager.h,
GattClient.h and GattServer.h.
* Modify nRF5xGattClient, nRF5xGattServer and nRF5xSecurityManager
classes so that they dynamically create their respective objects only if
needed. Previously the GattClient, GattServer and SecurityManager objects were
declared as static, which means that they were always present even though they
were not always needed. This increases memory consumption unnecessarily.
Furthermore, pointers to the object instances are stored in static members of
the classes as specified by the BLE API base classes. This ensures that
calls to shutdown do not require calls to getInstance() functions that would
otherwise result in undesired memory allocations.
* nRF5xGap object is always needed, so this remains allocated statically. But
the reference in Gap is pointed to this object.

The shutdown procedure is as follows:

1. The user calls ble.shutdown() which executes the code in nRF5xn::shutdown()
1. The SoftDevice is shutdown
1. The static members of Gap.h, SecurityManager.h, GattClient.h and
GattServer.h are called to clean up their own state.

If at any point an error occur during the last step, BLE_ERROR_INVALID_STATE is
returned.

Changed in this revision

--- a/source/nRF5xGap.cpp	Mon Jan 11 10:19:14 2016 +0000
+++ b/source/nRF5xGap.cpp	Mon Jan 11 10:19:15 2016 +0000
@@ -23,6 +23,9 @@
 
 nRF5xGap &nRF5xGap::getInstance() {
     static nRF5xGap m_instance;
+    if (gapInstance == NULL) {
+        gapInstance = &m_instance;
+    }
     return m_instance;
 }
 
@@ -338,6 +341,29 @@
 
 /**************************************************************************/
 /*!
+    @brief  Clear nRF5xGap's state.
+
+    @returns    ble_error_t
+
+    @retval     BLE_ERROR_NONE
+                Everything executed properly
+*/
+/**************************************************************************/
+ble_error_t nRF5xGap::cleanup(void)
+{
+    /* Clear all state that is from the parent, including private members */
+    if (Gap::cleanup() != BLE_ERROR_NONE) {
+        return BLE_ERROR_INVALID_STATE;
+    }
+
+    /* Clear derived class members */
+    m_connectionHandle = BLE_CONN_HANDLE_INVALID;
+
+    return BLE_ERROR_NONE;
+}
+
+/**************************************************************************/
+/*!
     @brief  Sets the 16-bit connection handle
 */
 /**************************************************************************/
@@ -356,7 +382,7 @@
     return m_connectionHandle;
 }
 
-/**************************************************************************/
+/**************5************************************************************/
 /*!
     @brief      Sets the BLE device address
 

--- a/source/nRF5xGap.h	Mon Jan 11 10:19:14 2016 +0000
+++ b/source/nRF5xGap.h	Mon Jan 11 10:19:15 2016 +0000
@@ -112,6 +112,9 @@
     }
 #endif
 
+protected:
+    virtual ble_error_t cleanup(void);
+
 private:
     bool    radioNotificationCallbackParam; /* parameter to be passed into the Timeout-generated radio notification callback. */
     Timeout radioNotificationTimeout;

--- a/source/nRF5xGattClient.cpp	Mon Jan 11 10:19:14 2016 +0000
+++ b/source/nRF5xGattClient.cpp	Mon Jan 11 10:19:15 2016 +0000
@@ -18,11 +18,10 @@
 
 nRF5xGattClient &
 nRF5xGattClient::getInstance(void) {
-    static nRF5xGattClient* nRFGattClientSingleton = NULL;
-    if (nRFGattClientSingleton == NULL) {
-        nRFGattClientSingleton = new nRF5xGattClient();
+    if (gattClientInstance == NULL) {
+        gattClientInstance = new nRF5xGattClient();
     }
-    return *nRFGattClientSingleton;
+    return (nRF5xGattClient &) *gattClientInstance;
 }
 
 #if !defined(TARGET_MCU_NRF51_16K_S110) && !defined(TARGET_MCU_NRF51_32K_S110)

--- a/source/nRF5xGattClient.h	Mon Jan 11 10:19:14 2016 +0000
+++ b/source/nRF5xGattClient.h	Mon Jan 11 10:19:15 2016 +0000
@@ -147,6 +147,25 @@
         }
     }
 
+protected:
+    /**
+     * @brief  Clear nRF5xGattClient's state.
+     *
+     * @return
+     *           BLE_ERROR_NONE if successful.
+     */
+    virtual ble_error_t cleanup(void) {
+        /* Clear all state that is from the parent, including private members */
+        if (GattClient::cleanup() != BLE_ERROR_NONE) {
+            return BLE_ERROR_INVALID_STATE;
+        }
+
+        /* Clear derived class members */
+        discovery.cleanup();
+
+        return BLE_ERROR_NONE;
+    }
+
 public:
     nRF5xGattClient() : discovery(this) {
         /* empty */

--- a/source/nRF5xGattServer.cpp	Mon Jan 11 10:19:14 2016 +0000
+++ b/source/nRF5xGattServer.cpp	Mon Jan 11 10:19:15 2016 +0000
@@ -23,8 +23,10 @@
 #include "nRF5xGap.h"
 
 nRF5xGattServer &nRF5xGattServer::getInstance(void) {
-    static nRF5xGattServer m_instance;
-    return m_instance;
+    if (gattServerInstance == NULL) {
+        gattServerInstance = new nRF5xGattServer();
+    }
+    return (nRF5xGattServer &) *gattServerInstance;
 }
 
 /**************************************************************************/
@@ -312,6 +314,33 @@
 
 /**************************************************************************/
 /*!
+    @brief  Clear nRF5xGattServer's state.
+
+    @returns    ble_error_t
+
+    @retval     BLE_ERROR_NONE
+                Everything executed properly
+*/
+/**************************************************************************/
+ble_error_t nRF5xGattServer::cleanup(void)
+{
+    /* Clear all state that is from the parent, including private members */
+    if (GattServer::cleanup() != BLE_ERROR_NONE) {
+        return BLE_ERROR_INVALID_STATE;
+    }
+
+    /* Clear derived class members */
+    memset(p_characteristics,        0, sizeof(p_characteristics));
+    memset(p_descriptors,            0, sizeof(p_descriptors));
+    memset(nrfCharacteristicHandles, 0, sizeof(ble_gatts_char_handles_t));
+    memset(nrfDescriptorHandles,     0, sizeof(nrfDescriptorHandles));
+    descriptorCount = 0;
+
+    return BLE_ERROR_NONE;
+}
+
+/**************************************************************************/
+/*!
     @brief  Callback handler for events getting pushed up from the SD
 */
 /**************************************************************************/

--- a/source/nRF5xGattServer.h	Mon Jan 11 10:19:14 2016 +0000
+++ b/source/nRF5xGattServer.h	Mon Jan 11 10:19:15 2016 +0000
@@ -1,98 +1,101 @@
-/* mbed Microcontroller Library
- * Copyright (c) 2006-2013 ARM Limited
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-#ifndef __NRF51822_GATT_SERVER_H__
-#define __NRF51822_GATT_SERVER_H__
-
-#include <stddef.h>
-
-#include "ble/blecommon.h"
-#include "ble.h" /* nordic ble */
-#include "ble/Gap.h"
-#include "ble/GattServer.h"
-
-class nRF5xGattServer : public GattServer
-{
-public:
-    static nRF5xGattServer &getInstance();
-
-    /* Functions that must be implemented from GattServer */
-    virtual ble_error_t addService(GattService &);
-    virtual ble_error_t read(GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP);
-    virtual ble_error_t read(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP);
-    virtual ble_error_t write(GattAttribute::Handle_t, const uint8_t[], uint16_t, bool localOnly = false);
-    virtual ble_error_t write(Gap::Handle_t connectionHandle, GattAttribute::Handle_t, const uint8_t[], uint16_t, bool localOnly = false);
-    virtual ble_error_t areUpdatesEnabled(const GattCharacteristic &characteristic, bool *enabledP);
-    virtual ble_error_t areUpdatesEnabled(Gap::Handle_t connectionHandle, const GattCharacteristic &characteristic, bool *enabledP);
-
-    /* nRF51 Functions */
-    void eventCallback(void);
-    void hwCallback(ble_evt_t *p_ble_evt);
-
-private:
-    const static unsigned BLE_TOTAL_CHARACTERISTICS = 20;
-    const static unsigned BLE_TOTAL_DESCRIPTORS     = 8;
-
-private:
-    /**
-     * resolve a value attribute to its owning characteristic.
-     * @param  valueHandle the value handle to be resolved.
-     * @return             characteristic index if a resolution is found, else -1.
-     */
-    int resolveValueHandleToCharIndex(GattAttribute::Handle_t valueHandle) const {
-        unsigned charIndex;
-        for (charIndex = 0; charIndex < characteristicCount; charIndex++) {
-            if (nrfCharacteristicHandles[charIndex].value_handle == valueHandle) {
-                return charIndex;
-            }
-        }
-
-        return -1;
-    }
-
-    /**
-     * resolve a CCCD attribute handle to its owning characteristic.
-     * @param  cccdHandle the CCCD handle to be resolved.
-     * @return             characteristic index if a resolution is found, else -1.
-     */
-    int resolveCCCDHandleToCharIndex(GattAttribute::Handle_t cccdHandle) const {
-        unsigned charIndex;
-        for (charIndex = 0; charIndex < characteristicCount; charIndex++) {
-            if (nrfCharacteristicHandles[charIndex].cccd_handle == cccdHandle) {
-                return charIndex;
-            }
-        }
-
-        return -1;
-    }
-
-private:
-    GattCharacteristic       *p_characteristics[BLE_TOTAL_CHARACTERISTICS];
-    ble_gatts_char_handles_t  nrfCharacteristicHandles[BLE_TOTAL_CHARACTERISTICS];
-    GattAttribute            *p_descriptors[BLE_TOTAL_DESCRIPTORS];
-    uint8_t                   descriptorCount;
-    uint16_t                  nrfDescriptorHandles[BLE_TOTAL_DESCRIPTORS];
-
-    nRF5xGattServer() : GattServer(), p_characteristics(), nrfCharacteristicHandles(), p_descriptors(), descriptorCount(0), nrfDescriptorHandles() {
-        /* empty */
-    }
-
-private:
-    nRF5xGattServer(const nRF5xGattServer &);
-    const nRF5xGattServer& operator=(const nRF5xGattServer &);
-};
-
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2013 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef __NRF51822_GATT_SERVER_H__
+#define __NRF51822_GATT_SERVER_H__
+
+#include <stddef.h>
+
+#include "ble/blecommon.h"
+#include "ble.h" /* nordic ble */
+#include "ble/Gap.h"
+#include "ble/GattServer.h"
+
+class nRF5xGattServer : public GattServer
+{
+public:
+    static nRF5xGattServer &getInstance();
+
+    /* Functions that must be implemented from GattServer */
+    virtual ble_error_t addService(GattService &);
+    virtual ble_error_t read(GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP);
+    virtual ble_error_t read(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t buffer[], uint16_t *lengthP);
+    virtual ble_error_t write(GattAttribute::Handle_t, const uint8_t[], uint16_t, bool localOnly = false);
+    virtual ble_error_t write(Gap::Handle_t connectionHandle, GattAttribute::Handle_t, const uint8_t[], uint16_t, bool localOnly = false);
+    virtual ble_error_t areUpdatesEnabled(const GattCharacteristic &characteristic, bool *enabledP);
+    virtual ble_error_t areUpdatesEnabled(Gap::Handle_t connectionHandle, const GattCharacteristic &characteristic, bool *enabledP);
+
+    /* nRF51 Functions */
+    void eventCallback(void);
+    void hwCallback(ble_evt_t *p_ble_evt);
+
+protected:
+    virtual ble_error_t cleanup(void);
+
+private:
+    const static unsigned BLE_TOTAL_CHARACTERISTICS = 20;
+    const static unsigned BLE_TOTAL_DESCRIPTORS     = 8;
+
+private:
+    /**
+     * resolve a value attribute to its owning characteristic.
+     * @param  valueHandle the value handle to be resolved.
+     * @return             characteristic index if a resolution is found, else -1.
+     */
+    int resolveValueHandleToCharIndex(GattAttribute::Handle_t valueHandle) const {
+        unsigned charIndex;
+        for (charIndex = 0; charIndex < characteristicCount; charIndex++) {
+            if (nrfCharacteristicHandles[charIndex].value_handle == valueHandle) {
+                return charIndex;
+            }
+        }
+
+        return -1;
+    }
+
+    /**
+     * resolve a CCCD attribute handle to its owning characteristic.
+     * @param  cccdHandle the CCCD handle to be resolved.
+     * @return             characteristic index if a resolution is found, else -1.
+     */
+    int resolveCCCDHandleToCharIndex(GattAttribute::Handle_t cccdHandle) const {
+        unsigned charIndex;
+        for (charIndex = 0; charIndex < characteristicCount; charIndex++) {
+            if (nrfCharacteristicHandles[charIndex].cccd_handle == cccdHandle) {
+                return charIndex;
+            }
+        }
+
+        return -1;
+    }
+
+private:
+    GattCharacteristic       *p_characteristics[BLE_TOTAL_CHARACTERISTICS];
+    ble_gatts_char_handles_t  nrfCharacteristicHandles[BLE_TOTAL_CHARACTERISTICS];
+    GattAttribute            *p_descriptors[BLE_TOTAL_DESCRIPTORS];
+    uint8_t                   descriptorCount;
+    uint16_t                  nrfDescriptorHandles[BLE_TOTAL_DESCRIPTORS];
+
+    nRF5xGattServer() : GattServer(), p_characteristics(), nrfCharacteristicHandles(), p_descriptors(), descriptorCount(0), nrfDescriptorHandles() {
+        /* empty */
+    }
+
+private:
+    nRF5xGattServer(const nRF5xGattServer &);
+    const nRF5xGattServer& operator=(const nRF5xGattServer &);
+};
+
 #endif // ifndef __NRF51822_GATT_SERVER_H__
\ No newline at end of file

--- a/source/nRF5xSecurityManager.cpp	Mon Jan 11 10:19:14 2016 +0000
+++ b/source/nRF5xSecurityManager.cpp	Mon Jan 11 10:19:15 2016 +0000
@@ -1,25 +1,24 @@
-/* mbed Microcontroller Library
- * Copyright (c) 2006-2013 ARM Limited
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-#include "nRF5xSecurityManager.h"
-
-nRF5xSecurityManager &nRF5xSecurityManager::getInstance(void) {
-    static nRF5xSecurityManager* m_instance = NULL;
-    if (m_instance == NULL) {
-        m_instance = new nRF5xSecurityManager();
-    }
-    return *m_instance;
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2013 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "nRF5xSecurityManager.h"
+
+nRF5xSecurityManager &nRF5xSecurityManager::getInstance(void) {
+    if (securityManagerInstance == NULL) {
+        securityManagerInstance = new nRF5xSecurityManager();
+    }
+    return (nRF5xSecurityManager &) *securityManagerInstance;
 }
\ No newline at end of file

--- a/source/nRF5xSecurityManager.h	Mon Jan 11 10:19:14 2016 +0000
+++ b/source/nRF5xSecurityManager.h	Mon Jan 11 10:19:15 2016 +0000
@@ -47,6 +47,21 @@
         return btle_purgeAllBondingState();
     }
 
+    /**
+     * @brief  Clear nRF5xSecurityManager's state.
+     *
+     * @return
+     *           BLE_ERROR_NONE if successful.
+     */
+    virtual ble_error_t cleanup(void)
+    {
+        if (SecurityManager::cleanup() != BLE_ERROR_NONE) {
+            return BLE_ERROR_INVALID_STATE;
+        }
+
+        return BLE_ERROR_NONE;
+    }
+
 public:
     nRF5xSecurityManager() {
         /* empty */

--- a/source/nRF5xServiceDiscovery.h	Mon Jan 11 10:19:14 2016 +0000
+++ b/source/nRF5xServiceDiscovery.h	Mon Jan 11 10:19:15 2016 +0000
@@ -99,6 +99,34 @@
         onTerminationCallback = callback;
     }
 
+    /**
+     * @brief  Clear nRF5xServiceDiscovery's state.
+     *
+     * @return
+     *           BLE_ERROR_NONE if successful.
+     */
+    virtual ble_error_t cleanup(void) {
+        /* Clear all state that is from the parent, including private members */
+        if (ServiceDiscovery::cleanup() != BLE_ERROR_NONE) {
+            return BLE_ERROR_INVALID_STATE;
+        }
+
+        /* Clear derived class members */
+        serviceIndex = 0;
+        numServices = 0;
+        characteristicIndex = 0;
+        numCharacteristics = 0;
+
+        state = INACTIVE;
+
+        serviceUUIDDiscoveryQueue.reset();
+        charUUIDDiscoveryQueue.reset();
+
+        onTerminationCallback = NULL;
+
+        return BLE_ERROR_NONE;
+    }
+
 private:
     ble_error_t launchCharacteristicDiscovery(Gap::Handle_t connectionHandle, Gap::Handle_t startHandle, Gap::Handle_t endHandle);
 

--- a/source/nRF5xn.cpp	Mon Jan 11 10:19:14 2016 +0000
+++ b/source/nRF5xn.cpp	Mon Jan 11 10:19:15 2016 +0000
@@ -104,16 +104,44 @@
     return BLE_ERROR_NONE;
 }
 
+/**************************************************************************/
+/*!
+    @brief  Purge the BLE stack of GATT and GAP state.
+
+    @returns    ble_error_t
+
+    @retval     BLE_ERROR_NONE
+                Everything executed properly
+
+    @note  When using S110, GattClient::shutdown() will not be called
+           since Gatt client features are not supported.
+*/
+/**************************************************************************/
 ble_error_t nRF5xn::shutdown(void)
 {
     if (!initialized) {
         return BLE_ERROR_INITIALIZATION_INCOMPLETE;
     }
 
+    /* Shutdown the SoftDevice */
     if(softdevice_handler_sd_disable() != NRF_SUCCESS) {
         return BLE_STACK_BUSY;
     }
 
+    /* Shutdown the BLE API and nRF51 glue code */
+#if !defined(TARGET_MCU_NRF51_16K_S110) && !defined(TARGET_MCU_NRF51_32K_S110)
+    if (GattServer::shutdown()      != BLE_ERROR_NONE ||
+        SecurityManager::shutdown() != BLE_ERROR_NONE ||
+        GattClient::shutdown()      != BLE_ERROR_NONE ||
+        Gap::shutdown()             != BLE_ERROR_NONE) {
+#else
+    if (GattServer::shutdown()      != BLE_ERROR_NONE ||
+        SecurityManager::shutdown() != BLE_ERROR_NONE ||
+        Gap::shutdown()             != BLE_ERROR_NONE) {
+#endif
+        return BLE_ERROR_INVALID_STATE;
+    }
+
     initialized = false;
     return BLE_ERROR_NONE;
 }