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 contolled 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 47 #ifndef OPENTHREAD_PLATFORM_MULTIPAN_H_ 48 #define OPENTHREAD_PLATFORM_MULTIPAN_H_ 49 50 #include <stdint.h> 51 52 #include <openthread/error.h> 53 #include <openthread/instance.h> 54 55 #ifdef __cplusplus 56 extern "C" { 57 #endif 58 59 /** 60 * @addtogroup plat-multipan 61 * 62 * @brief 63 * This module includes the platform abstraction for multipan support. 64 * 65 * @{ 66 * 67 */ 68 69 /** 70 * Get instance currently in control of the radio. 71 * 72 * If radio does not operate in parallel on all interfaces, this function returns an instance object with granted 73 * radio access. 74 * 75 * @param[out] aInstance Pointer to the variable for storing the active instance pointer. 76 * 77 * @retval OT_ERROR_NONE Successfully retrieved the property. 78 * @retval OT_ERROR_NOT_IMPLEMENTED Failed due to lack of the support in radio. 79 * @retval OT_ERROR_INVALID_COMMAND Platform supports all interfaces simultaneously. 80 * 81 */ 82 otError otPlatMultipanGetActiveInstance(otInstance **aInstance); 83 84 /** 85 * Set `aInstance` as the current active instance controlling radio. 86 * 87 * This function allows selecting the currently active instance on platforms that do not support parallel 88 * communication on multiple interfaces. In other words, if more than one instance is in a receive state, calling 89 * #otPlatMultipanSetActiveInstance guarantees that specified instance will be the one receiving. This function returns 90 * if the request was received properly. After interface switching is complete, the platform should call 91 * #otPlatMultipanSwitchoverDone. Switching interfaces may take longer if `aCompletePending` is set true. 92 * 93 * @param[in] aInstance The OpenThread instance structure. 94 * @param[in] aCompletePending True if ongoing radio operation should complete before interface switch (Soft switch), 95 * false for force switch. 96 * 97 * @retval OT_ERROR_NONE Successfully set the property. 98 * @retval OT_ERROR_BUSY Failed due to another operation ongoing. 99 * @retval OT_ERROR_NOT_IMPLEMENTED Failed due to unknown instance or more instances than interfaces available. 100 * @retval OT_ERROR_INVALID_COMMAND Platform supports all interfaces simultaneously. 101 * @retval OT_ERROR_ALREADY Given interface is already active. 102 * 103 */ 104 otError otPlatMultipanSetActiveInstance(otInstance *aInstance, bool aCompletePending); 105 106 /** 107 * The platform completed the interface switching procedure. 108 * 109 * Should be invoked immediately after processing #otPlatMultipanSetActiveInstance if no delay is needed, or if 110 * some longer radio operations need to complete first, after the switch in interfaces is fully complete. 111 * 112 * @param[in] aInstance The OpenThread instance structure. 113 * @param[in] aSuccess True if successfully switched the interfaces, false if switching failed. 114 * 115 */ 116 extern void otPlatMultipanSwitchoverDone(otInstance *aInstance, bool aSuccess); 117 118 /** 119 * Get the instance pointer corresponding to the given IID. 120 * 121 * @param[in] aIid The IID of the interface. 122 * 123 * @retval Instance pointer if aIid is has an instance assigned, nullptr otherwise. 124 */ 125 otInstance *otPlatMultipanIidToInstance(uint8_t aIid); 126 127 /** 128 * Get the IID corresponding to the given OpenThread instance pointer. 129 * 130 * @param[in] aInstance The OpenThread instance structure. 131 * 132 * @retval IID of the given instance, broadcast IID otherwise. 133 */ 134 uint8_t otPlatMultipanInstanceToIid(otInstance *aInstance); 135 136 /** 137 * @} 138 * 139 */ 140 141 #ifdef __cplusplus 142 } // end of extern "C" 143 #endif 144 145 #endif // OPENTHREAD_PLATFORM_MULTIPAN_H_ 146
