1 /* 2 * Copyright (c) 2023, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file defines the multipan interface for OpenThread. 33 * 34 * Multipan RCP is a feature that allows single RCP operate in multiple networks. 35 * 36 * Currently we support two types of multipan RCP: 37 * - Full multipan: RCP operates in parallel on both networks (for example using more than one transceiver) 38 * - Switching RCP: RCP can communicate only with one network at a time and requires network switching mechanism. 39 * Switching can be automatic (for example time based, radio sleep based) or manually controlled by 40 * the host. 41 * 42 * Full multipan RCP and Automatic Switching RCP do not require any special care from the host side. 43 * Manual Switching RCP requires host to switch currently active network. 44 */ 45 46 #ifndef OPENTHREAD_PLATFORM_MULTIPAN_H_ 47 #define OPENTHREAD_PLATFORM_MULTIPAN_H_ 48 49 #include <stdint.h> 50 51 #include <openthread/error.h> 52 #include <openthread/instance.h> 53 54 #ifdef __cplusplus 55 extern "C" { 56 #endif 57 58 /** 59 * @addtogroup plat-multipan 60 * 61 * @brief 62 * This module includes the platform abstraction for multipan support. 63 * 64 * @{ 65 */ 66 67 /** 68 * Get instance currently in control of the radio. 69 * 70 * If radio does not operate in parallel on all interfaces, this function returns an instance object with granted 71 * radio access. 72 * 73 * @param[out] aInstance Pointer to the variable for storing the active instance pointer. 74 * 75 * @retval OT_ERROR_NONE Successfully retrieved the property. 76 * @retval OT_ERROR_NOT_IMPLEMENTED Failed due to lack of the support in radio. 77 * @retval OT_ERROR_INVALID_COMMAND Platform supports all interfaces simultaneously. 78 */ 79 otError otPlatMultipanGetActiveInstance(otInstance **aInstance); 80 81 /** 82 * Set `aInstance` as the current active instance controlling radio. 83 * 84 * This function allows selecting the currently active instance on platforms that do not support parallel 85 * communication on multiple interfaces. In other words, if more than one instance is in a receive state, calling 86 * #otPlatMultipanSetActiveInstance guarantees that specified instance will be the one receiving. This function returns 87 * if the request was received properly. After interface switching is complete, the platform should call 88 * #otPlatMultipanSwitchoverDone. Switching interfaces may take longer if `aCompletePending` is set true. 89 * 90 * @param[in] aInstance The OpenThread instance structure. 91 * @param[in] aCompletePending True if ongoing radio operation should complete before interface switch (Soft switch), 92 * false for force switch. 93 * 94 * @retval OT_ERROR_NONE Successfully set the property. 95 * @retval OT_ERROR_BUSY Failed due to another operation ongoing. 96 * @retval OT_ERROR_NOT_IMPLEMENTED Failed due to unknown instance or more instances than interfaces available. 97 * @retval OT_ERROR_INVALID_COMMAND Platform supports all interfaces simultaneously. 98 * @retval OT_ERROR_ALREADY Given interface is already active. 99 */ 100 otError otPlatMultipanSetActiveInstance(otInstance *aInstance, bool aCompletePending); 101 102 /** 103 * The platform completed the interface switching procedure. 104 * 105 * Should be invoked immediately after processing #otPlatMultipanSetActiveInstance if no delay is needed, or if 106 * some longer radio operations need to complete first, after the switch in interfaces is fully complete. 107 * 108 * @param[in] aInstance The OpenThread instance structure. 109 * @param[in] aSuccess True if successfully switched the interfaces, false if switching failed. 110 */ 111 extern void otPlatMultipanSwitchoverDone(otInstance *aInstance, bool aSuccess); 112 113 /** 114 * Get the instance pointer corresponding to the given IID. 115 * 116 * @param[in] aIid The IID of the interface. 117 * 118 * @retval Instance pointer if aIid is has an instance assigned, nullptr otherwise. 119 */ 120 otInstance *otPlatMultipanIidToInstance(uint8_t aIid); 121 122 /** 123 * Get the IID corresponding to the given OpenThread instance pointer. 124 * 125 * @param[in] aInstance The OpenThread instance structure. 126 * 127 * @retval IID of the given instance, broadcast IID otherwise. 128 */ 129 uint8_t otPlatMultipanInstanceToIid(otInstance *aInstance); 130 131 /** 132 * @} 133 */ 134 135 #ifdef __cplusplus 136 } // end of extern "C" 137 #endif 138 139 #endif // OPENTHREAD_PLATFORM_MULTIPAN_H_ 140
