[multipan]Rework switchover API

Separated interface switching API into separate file. Added tests for interface switching. Signed-off-by: Marek Porwisz <[email protected]>
SiliconLabs · Sep 11, 2023 · 646c850 · 646c850
1 parent 1a5f7fe
commit 646c850
Show file tree

Hide file tree

Showing 30 changed files with 490 additions and 252 deletions.
diff --git a/examples/platforms/simulation/CMakeLists.txt b/examples/platforms/simulation/CMakeLists.txt
@@ -80,6 +80,7 @@ add_library(openthread-simulation
     infra_if.c
     logging.c
     misc.c
+    multipan.c
     radio.c
     spi-stubs.c
     system.c

diff --git a/examples/platforms/simulation/multipan.c b/examples/platforms/simulation/multipan.c
@@ -0,0 +1,66 @@
+/*
+ *  Copyright (c) 2023, The OpenThread Authors.
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions are met:
+ *  1. Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *  2. Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *  3. Neither the name of the copyright holder nor the
+ *     names of its contributors may be used to endorse or promote products
+ *     derived from this software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ *  POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "platform-simulation.h"
+
+#include <errno.h>
+#include <sys/time.h>
+
+#include <openthread/platform/multipan.h>
+
+#if OPENTHREAD_CONFIG_MULTIPAN_RCP_ENABLE
+static otInstance *sActiveInstance;
+#endif
+
+otError otPlatMultipanGetActiveInstance(otInstance **aInstance)
+{
+    otError error = OT_ERROR_NOT_IMPLEMENTED;
+    OT_UNUSED_VARIABLE(aInstance);
+
+#if OPENTHREAD_CONFIG_MULTIPAN_RCP_ENABLE
+    *aInstance = sActiveInstance;
+    error      = OT_ERROR_NONE;
+#endif
+
+    return error;
+}
+
+otError otPlatMultipanSetActiveInstance(otInstance *aInstance, bool aCompletePending)
+{
+    otError error = OT_ERROR_NOT_IMPLEMENTED;
+
+    OT_UNUSED_VARIABLE(aInstance);
+    OT_UNUSED_VARIABLE(aCompletePending);
+
+#if OPENTHREAD_CONFIG_MULTIPAN_RCP_ENABLE
+    sActiveInstance = aInstance;
+    error           = OT_ERROR_NONE;
+#endif
+
+    return error;
+}
diff --git a/examples/platforms/simulation/radio.c b/examples/platforms/simulation/radio.c
@@ -167,10 +167,6 @@ static otMacKeyMaterial sCurrKey;
 static otMacKeyMaterial sNextKey;
 static otRadioKeyType   sKeyType;
 
-#if OPENTHREAD_CONFIG_MULTIPAN_RCP_ENABLE
-static volatile uint8_t sRadioInterface;
-#endif
-
 static int8_t GetRssi(uint16_t aChannel);
 
 #if OPENTHREAD_SIMULATION_VIRTUAL_TIME == 0
@@ -360,36 +356,6 @@ static uint16_t crc16_citt(uint16_t aFcs, uint8_t aByte)
     return (aFcs >> 8) ^ sFcsTable[(aFcs ^ aByte) & 0xff];
 }
 
-otError otPlatGetActiveMultipanInterface(otInstance *aInstance, uint8_t *aRadioInterface)
-{
-    otError error = OT_ERROR_NOT_IMPLEMENTED;
-    OT_UNUSED_VARIABLE(aInstance);
-    OT_UNUSED_VARIABLE(aRadioInterface);
-
-#if OPENTHREAD_CONFIG_MULTIPAN_RCP_ENABLE
-    *aRadioInterface = sRadioInterface;
-    error            = OT_ERROR_NONE;
-#endif
-
-    return error;
-}
-
-otError otPlatSetActiveMultipanInterface(otInstance *aInstance, uint8_t aRadioInterface, bool aCompletePending)
-{
-    otError error = OT_ERROR_NOT_IMPLEMENTED;
-
-    OT_UNUSED_VARIABLE(aInstance);
-    OT_UNUSED_VARIABLE(aRadioInterface);
-    OT_UNUSED_VARIABLE(aCompletePending);
-
-#if OPENTHREAD_CONFIG_MULTIPAN_RCP_ENABLE
-    sRadioInterface = aRadioInterface;
-    error           = OT_ERROR_NONE;
-#endif
-
-    return error;
-}
-
 void otPlatRadioGetIeeeEui64(otInstance *aInstance, uint8_t *aIeeeEui64)
 {
     OT_UNUSED_VARIABLE(aInstance);

diff --git a/include/openthread/BUILD.gn b/include/openthread/BUILD.gn
@@ -97,6 +97,7 @@ source_set("openthread") {
     "platform/memory.h",
     "platform/messagepool.h",
     "platform/misc.h",
+    "platform/multipan.h",
     "platform/otns.h",
     "platform/radio.h",
     "platform/settings.h",

diff --git a/include/openthread/instance.h b/include/openthread/instance.h
@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (356)
+#define OPENTHREAD_API_VERSION (357)
 
 /**
  * @addtogroup api-instance

diff --git a/include/openthread/link_raw.h b/include/openthread/link_raw.h
@@ -51,24 +51,6 @@ extern "C" {
  *
  */
 
-/**
- * This function pointer on switchover completion
- *
- * @param[in]  aInstance    A pointer to an OpenThread instance.
- * @param[in]  aSuccess     Informs if the operation completed successful or not.
- *
- */
-typedef void (*otLinkRawSwitchoverDone)(otInstance *aInstance, bool aSuccess);
-
-/**
- * This function sets the radio switchover complete callback.
- *
- * @param[in] aInstance     A pointer to an OpenThread instance.
- * @param[in] aCallback     A pointer to a function to call.
- *
- */
-void otLinkRawSetSwitchoverDone(otInstance *aInstance, otLinkRawSwitchoverDone aCallback);
-
 /**
  * Pointer on receipt of a IEEE 802.15.4 frame.
  *

diff --git a/include/openthread/platform/multipan.h b/include/openthread/platform/multipan.h
@@ -0,0 +1,117 @@
+/*
+ *  Copyright (c) 2023, The OpenThread Authors.
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions are met:
+ *  1. Redistributions of source code must retain the above copyright
+ *     notice, this list of conditions and the following disclaimer.
+ *  2. Redistributions in binary form must reproduce the above copyright
+ *     notice, this list of conditions and the following disclaimer in the
+ *     documentation and/or other materials provided with the distribution.
+ *  3. Neither the name of the copyright holder nor the
+ *     names of its contributors may be used to endorse or promote products
+ *     derived from this software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ *  POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/**
+ * @file
+ * @brief
+ *   This file defines the radio interface for OpenThread.
+ *
+ */
+
+#ifndef OPENTHREAD_PLATFORM_MULTIPAN_H_
+#define OPENTHREAD_PLATFORM_MULTIPAN_H_
+
+#include <stdint.h>
+
+#include <openthread/error.h>
+#include <openthread/instance.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @addtogroup plat-multipan
+ *
+ * @brief
+ *   This module includes the platform abstraction for multipan support.
+ *
+ * @{
+ *
+ */
+
+/**
+ * Get instance currently in control of the radio.
+ *
+ * If radio does not operate in parallel on all interfaces, this function returns instance object with granted radio
+ access
+ *
+ * @param[out]  aInstance        Pointer to the variable for storing active instance pointer
+
+ * @retval  OT_ERROR_NONE               Successfully got the property.
+ * @retval  OT_ERROR_NOT_IMPLEMENTED    Failed due lack of the support in radio or platform supprts
+ *                                      all interfaces simultaneously
+ *                                      (i.e. no active/inactive interface concept in the platform level).
+ *
+ */
+otError otPlatMultipanGetActiveInstance(otInstance **aInstance);
+
+/**
+ * Set `aInstance` as the current active instance controlling radio
+ *
+ * This function allows selecting currently active instance on platforms that do not support parallel
+ * communication on multiple interfaces. I.e. if more than one instance is in receive state calling
+ * otPlatMultipanSetActiveInstance guarantees that specified instance will be the one receiving. This function returns
+ * if the request was received properly. After interface switching is complete platform should call
+ * otPlatMultipanSwitchoverDone. Switching interfaces may take longer if aCompletePending is set true.
+ *
+ * @param[in] aInstance         The OpenThread instance structure.
+ * @param[in] aCompletePending  True if ongoing radio operation should complete before interface switch (Soft switch),
+ * false for force switch.
+ *
+ * @retval  OT_ERROR_NONE               Successfully set the property.
+ * @retval  OT_ERROR_BUSY               Failed due to another operation on going.
+ * @retval  OT_ERROR_NOT_IMPLEMENTED    Failed due to unknown/to many instances or platform supprts all interfaces
+ * simultaneously (i.e. no active/inactive concept in the platform level)
+ * @retval  OT_ERROR_ALREADY            Given interface is already active.
+ *
+ */
+otError otPlatMultipanSetActiveInstance(otInstance *aInstance, bool aCompletePending);
+
+/**
+ * The platform completed the interface switching procedure.
+ *
+ * Should be invoked immediately after processing otPlatMultipanSetActiveInstance if no delay is needed or after
+ * interfaces switch is fully complete if some longer radio operations need to complete first.
+ *
+ * @param[in]  aInstance The OpenThread instance structure.
+ * @param[in]  aSuccess  True if successfully switched the interfaces, false if switching failed.
+ *
+ */
+extern void otPlatMultipanSwitchoverDone(otInstance *aInstance, bool aSuccess);
+
+/**
+ * @}
+ *
+ */
+
+#ifdef __cplusplus
+} // end of extern "C"
+#endif
+
+#endif // OPENTHREAD_PLATFORM_MULTIPAN_H_
diff --git a/include/openthread/platform/radio.h b/include/openthread/platform/radio.h
@@ -505,44 +505,6 @@ void otPlatRadioSetExtendedAddress(otInstance *aInstance, const otExtAddress *aE
  */
 void otPlatRadioSetShortAddress(otInstance *aInstance, otShortAddress aShortAddress);
 
-/**
- * Get currently active radio interface.
- *
- * @param[in]  aInstance      The OpenThread instance structure.
- * @param[out] aRadioInterface   Pointer to the variable for storing radio interface index
-
- * @retval  OT_ERROR_NONE               Successfully got the property.
- * @retval  OT_ERROR_NOT_IMPLEMENTED    Failed due lack of the support in radio or platform supprts
- *                                      all interfaces simultaneously
- *                                      (i.e. no active/inactive interface concept in the platform level).
- *
- */
-otError otPlatGetActiveMultipanInterface(otInstance *aInstance, uint8_t *aRadioInterface);
-
-/**
- * Select active radio interface.
- *
- * This function allows selecting currently active radio interface on platforms that do not support parallel
- * communication on multiple interfaces. I.e. if more than one interface is in receive state calling
- * otPlatSetActiveMultipanInterface guarantees that specified interface will be the one receiving. This function returns
- * if the request was received properly. After interface switching is complete platform should call
- * otPlatRadioSwitchoverDone. Switching interfaces may take longer if aCompletePending is set true.
- *
- * @param[in] aInstance         The OpenThread instance structure.
- * @param[in] aRadioInterface   Radio interface to make active.
- * @param[in] aCompletePending  True if ongoing radio operation should complete before interface switch (Soft switch),
- * false for force switch.
- *
- * @retval  OT_ERROR_NONE               Successfully set the property.
- * @retval  OT_ERROR_BUSY               Failed due to another operation on going.
- * @retval  OT_ERROR_NOT_IMPLEMENTED    Failed due to lack of support in radio for the given interface id or
- *                                      platform supprts all interfaces simultaneously
- *                                      (i.e. no active/inactive interface concept in the platform level)
- * @retval  OT_ERROR_ALREADY            Given interface is already active.
- *
- */
-otError otPlatSetActiveMultipanInterface(otInstance *aInstance, uint8_t aRadioInterface, bool aCompletePending);
-
 /**
  * Get the radio's transmit power in dBm.
  *
@@ -836,18 +798,6 @@ extern void otPlatRadioReceiveDone(otInstance *aInstance, otRadioFrame *aFrame,
  */
 extern void otPlatDiagRadioReceiveDone(otInstance *aInstance, otRadioFrame *aFrame, otError aError);
 
-/**
- * The radio driver completed the interface switching procedure.
- *
- * Should be invoked immediately after processing otPlatSetMultipanInterface if no delay is needed or after interfaces
- * switch is fully complete if some longer radio operations need to complete first.
- *
- * @param[in]  aInstance The OpenThread instance structure.
- * @param[in]  aSuccess  True if successfully switched the interfaces, false if switching failed.
- *
- */
-extern void otPlatRadioSwitchoverDone(otInstance *aInstance, bool aSuccess);
-
 /**
  * Get the radio transmit frame buffer.
  *

diff --git a/src/core/api/link_raw_api.cpp b/src/core/api/link_raw_api.cpp
@@ -49,11 +49,6 @@
 
 using namespace ot;
 
-void otLinkRawSetSwitchoverDone(otInstance *aInstance, otLinkRawSwitchoverDone aCallback)
-{
-    AsCoreType(aInstance).Get<Mac::LinkRaw>().SetSwitchoverDone(aCallback);
-}
-
 otError otLinkRawSetReceiveDone(otInstance *aInstance, otLinkRawReceiveDone aCallback)
 {
     return AsCoreType(aInstance).Get<Mac::LinkRaw>().SetReceiveDone(aCallback);

diff --git a/src/core/mac/link_raw.cpp b/src/core/mac/link_raw.cpp
@@ -56,7 +56,6 @@ LinkRaw::LinkRaw(Instance &aInstance)
     , mReceiveChannel(OPENTHREAD_CONFIG_DEFAULT_CHANNEL)
     , mPanId(kPanIdBroadcast)
     , mReceiveDoneCallback(nullptr)
-    , mSwitchoverDoneCallback(nullptr)
     , mTransmitDoneCallback(nullptr)
     , mEnergyScanDoneCallback(nullptr)
 #if OPENTHREAD_RADIO
@@ -82,8 +81,6 @@ void LinkRaw::Init(void)
 #endif
 }
 
-void LinkRaw::SetSwitchoverDone(otLinkRawSwitchoverDone aCallback) { mSwitchoverDoneCallback = aCallback; }
-
 Error LinkRaw::SetReceiveDone(otLinkRawReceiveDone aCallback)
 {
     Error error  = kErrorNone;
@@ -182,14 +179,6 @@ Error LinkRaw::Receive(void)
     return error;
 }
 
-void LinkRaw::InvokeSwitchoverDone(bool aSuccess)
-{
-    if (mSwitchoverDoneCallback)
-    {
-        mSwitchoverDoneCallback(&GetInstance(), aSuccess);
-    }
-}
-
 void LinkRaw::InvokeReceiveDone(RxFrame *aFrame, Error aError)
 {
     LogDebg("ReceiveDone(%d bytes), error:%s", (aFrame != nullptr) ? aFrame->mLength : 0, ErrorToString(aError));