1 /* 2 * Copyright (c) 2016, 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 platform-specific functions needed by OpenThread's example applications. 33 */ 34 35 #ifndef OPENTHREAD_SYSTEM_H_ 36 #define OPENTHREAD_SYSTEM_H_ 37 38 #include <setjmp.h> 39 #include <stdbool.h> 40 #include <stdint.h> 41 #include <stdio.h> 42 #include <sys/select.h> 43 44 #include <openthread/error.h> 45 #include <openthread/instance.h> 46 #include <openthread/ip6.h> 47 #include <openthread/platform/misc.h> 48 49 #include "lib/spinel/coprocessor_type.h" 50 #include "lib/spinel/radio_spinel_metrics.h" 51 52 #ifdef __cplusplus 53 extern "C" { 54 #endif 55 56 /** 57 * Represents default parameters for the SPI interface. 58 */ 59 enum 60 { 61 OT_PLATFORM_CONFIG_SPI_DEFAULT_MODE = 0, ///< Default SPI Mode: CPOL=0, CPHA=0. 62 OT_PLATFORM_CONFIG_SPI_DEFAULT_SPEED_HZ = 1000000, ///< Default SPI speed in hertz. 63 OT_PLATFORM_CONFIG_SPI_DEFAULT_CS_DELAY_US = 20, ///< Default delay after SPI C̅S̅ assertion, in µsec. 64 OT_PLATFORM_CONFIG_SPI_DEFAULT_RESET_DELAY_MS = 0, ///< Default delay after R̅E̅S̅E̅T̅ assertion, in milliseconds. 65 OT_PLATFORM_CONFIG_SPI_DEFAULT_ALIGN_ALLOWANCE = 66 16, ///< Default maximum number of 0xFF bytes to clip from start of MISO frame. 67 OT_PLATFORM_CONFIG_SPI_DEFAULT_SMALL_PACKET_SIZE = 68 32, ///< Default smallest SPI packet size we can receive in a single transaction. 69 OT_PLATFORM_CONFIG_MAX_RADIO_URLS = 2, ///< Max number of Radio URLs. 70 }; 71 72 /** 73 * Represents the Co-processor URLs. 74 */ 75 typedef struct otPlatformCoprocessorUrls 76 { 77 const char *mUrls[OT_PLATFORM_CONFIG_MAX_RADIO_URLS]; ///< Co-processor URLs. 78 uint8_t mNum; ///< Number of Co-processor URLs. 79 } otPlatformCoprocessorUrls; 80 81 /** 82 * Represents platform specific configurations. 83 */ 84 typedef struct otPlatformConfig 85 { 86 const char *mBackboneInterfaceName; ///< Backbone network interface name. 87 const char *mInterfaceName; ///< Thread network interface name. 88 otPlatformCoprocessorUrls mCoprocessorUrls; ///< Coprocessor URLs. 89 int mRealTimeSignal; ///< The real-time signal for microsecond timer. 90 uint32_t mSpeedUpFactor; ///< Speed up factor. 91 bool mPersistentInterface; ///< Whether persistent the interface 92 bool mDryRun; ///< If 'DryRun' is set, the posix daemon will exit 93 ///< directly after initialization. 94 CoprocessorType mCoprocessorType; ///< The co-processor type. This field is used to pass 95 ///< the type to the app layer. 96 } otPlatformConfig; 97 98 /** 99 * Represents the platform spinel driver structure. 100 */ 101 typedef struct otSpinelDriver otSpinelDriver; 102 103 /** 104 * Gets the instance of the spinel driver; 105 * 106 * @note This API is used for external projects to get the instance of `SpinelDriver` to customize 107 * different spinel handlings. 108 * 109 * @returns A pointer to the spinel driver instance. 110 */ 111 otSpinelDriver *otSysGetSpinelDriver(void); 112 113 /** 114 * Initializes the co-processor and the spinel driver. 115 * 116 * @note This API will initialize the co-processor by resetting it and return the co-processor type. 117 * If this API is called, the upcoming call of `otSysInit` won't initialize the co-processor 118 * and the spinel driver again, unless `otSysDeinit` is called. This API is used to get the 119 * co-processor type without calling `otSysInit`. 120 * 121 * @param[in] aUrls The URLs to initialize the co-processor. 122 * 123 * @returns The co-processor type. 124 */ 125 CoprocessorType otSysInitCoprocessor(otPlatformCoprocessorUrls *aUrls); 126 127 /** 128 * Performs all platform-specific initialization of OpenThread's drivers and initializes the OpenThread 129 * instance. 130 * 131 * @note This function is not called by the OpenThread library. Instead, the system/RTOS should call this function 132 * when initialization of OpenThread's drivers is most appropriate. 133 * 134 * @param[in] aPlatformConfig Platform configuration structure. 135 * 136 * @returns A pointer to the OpenThread instance. 137 */ 138 otInstance *otSysInit(otPlatformConfig *aPlatformConfig); 139 140 /** 141 * Finalizes the OpenThread instance and performs all platform-specific deinitialization for OpenThread's 142 * drivers. 143 * 144 * @note This function is not called by the OpenThread library. Instead, the system/RTOS should call this function 145 * when deinitialization of OpenThread's drivers is most appropriate. 146 */ 147 void otSysDeinit(void); 148 149 /** 150 * Represents a context for a select() based mainloop. 151 */ 152 typedef struct otSysMainloopContext 153 { 154 fd_set mReadFdSet; ///< The read file descriptors. 155 fd_set mWriteFdSet; ///< The write file descriptors. 156 fd_set mErrorFdSet; ///< The error file descriptors. 157 int mMaxFd; ///< The max file descriptor. 158 struct timeval mTimeout; ///< The timeout. 159 } otSysMainloopContext; 160 161 /** 162 * Updates the file descriptor sets with file descriptors used by OpenThread drivers. 163 * 164 * @param[in] aInstance The OpenThread instance structure. 165 * @param[in,out] aMainloop A pointer to the mainloop context. 166 */ 167 void otSysMainloopUpdate(otInstance *aInstance, otSysMainloopContext *aMainloop); 168 169 /** 170 * Polls OpenThread's mainloop. 171 * 172 * @param[in,out] aMainloop A pointer to the mainloop context. 173 * 174 * @returns value returned from select(). 175 */ 176 int otSysMainloopPoll(otSysMainloopContext *aMainloop); 177 178 /** 179 * Performs all platform-specific processing for OpenThread's example applications. 180 * 181 * @note This function is not called by the OpenThread library. Instead, the system/RTOS should call this function 182 * in the main loop when processing OpenThread's drivers is most appropriate. 183 * 184 * @param[in] aInstance The OpenThread instance structure. 185 * @param[in] aMainloop A pointer to the mainloop context. 186 */ 187 void otSysMainloopProcess(otInstance *aInstance, const otSysMainloopContext *aMainloop); 188 189 /** 190 * Returns the radio url help string. 191 * 192 * @returns the radio url help string. 193 */ 194 const char *otSysGetRadioUrlHelpString(void); 195 196 extern otPlatResetReason gPlatResetReason; 197 198 /** 199 * Returns the Thread network interface name. 200 * 201 * @returns The Thread network interface name. 202 */ 203 const char *otSysGetThreadNetifName(void); 204 205 /** 206 * Returns the Thread network interface index. 207 * 208 * @returns The Thread network interface index. 209 */ 210 unsigned int otSysGetThreadNetifIndex(void); 211 212 /** 213 * Returns the infrastructure network interface name. 214 * 215 * @returns The infrastructure network interface name, or `nullptr` if not specified. 216 */ 217 const char *otSysGetInfraNetifName(void); 218 219 /** 220 * Returns the infrastructure network interface index. 221 * 222 * @returns The infrastructure network interface index. 223 */ 224 uint32_t otSysGetInfraNetifIndex(void); 225 226 /** 227 * Returns the radio spinel metrics. 228 * 229 * @returns The radio spinel metrics. 230 */ 231 const otRadioSpinelMetrics *otSysGetRadioSpinelMetrics(void); 232 233 /** 234 * Returns the RCP interface metrics. 235 * 236 * @returns The RCP interface metrics. 237 */ 238 const otRcpInterfaceMetrics *otSysGetRcpInterfaceMetrics(void); 239 240 /** 241 * Returns the ifr_flags of the infrastructure network interface. 242 * 243 * @returns The ifr_flags of infrastructure network interface. 244 */ 245 uint32_t otSysGetInfraNetifFlags(void); 246 247 typedef struct otSysInfraNetIfAddressCounters 248 { 249 uint32_t mLinkLocalAddresses; 250 uint32_t mUniqueLocalAddresses; 251 uint32_t mGlobalUnicastAddresses; 252 } otSysInfraNetIfAddressCounters; 253 254 /** 255 * This functions counts the number of addresses on the infrastructure network interface. 256 * 257 * @param[out] aAddressCounters The counters of addresses on infrastructure network interface. 258 */ 259 void otSysCountInfraNetifAddresses(otSysInfraNetIfAddressCounters *aAddressCounters); 260 261 /** 262 * Sets the infrastructure network interface and the ICMPv6 socket. 263 * 264 * This function specifies the network interface name and the ICMPv6 socket on that interface. After calling this 265 * function, the caller can call otBorderRoutingInit() to let Border Routing work on that interface. 266 * 267 * @param[in] aInfraNetifName The name of the infrastructure network interface. 268 * @param[in] aIcmp6Socket A SOCK_RAW socket running on the infrastructure network interface. 269 */ 270 void otSysSetInfraNetif(const char *aInfraNetifName, int aIcmp6Socket); 271 272 /** 273 * Returns TRUE if the infrastructure interface is running. 274 * 275 * @returns TRUE if the infrastructure interface is running, FALSE if not. 276 */ 277 bool otSysInfraIfIsRunning(void); 278 279 /** 280 * Initializes the CLI module using the daemon. 281 * 282 * This function initializes the CLI module, and assigns the daemon to handle 283 * the CLI output. This function can be invoked multiple times. The typical use case 284 * is that, after OTBR/vendor_server's CLI output redirection, it uses this API to 285 * restore the original daemon's CLI output. 286 * 287 * @param[in] aInstance The OpenThread instance structure. 288 */ 289 void otSysCliInitUsingDaemon(otInstance *aInstance); 290 291 /** 292 * Sets whether to retrieve upstream DNS servers from "resolv.conf". 293 * 294 * @param[in] aEnabled TRUE if enable retrieving upstream DNS servers from "resolv.conf", FALSE otherwise. 295 */ 296 void otSysUpstreamDnsServerSetResolvConfEnabled(bool aEnabled); 297 298 /** 299 * Sets the upstream DNS server list. 300 * 301 * @param[in] aUpstreamDnsServers A pointer to the list of upstream DNS server addresses. Each address could be an IPv6 302 * address or an IPv4-mapped IPv6 address. 303 * @param[in] aNumServers The number of upstream DNS servers. 304 */ 305 void otSysUpstreamDnsSetServerList(const otIp6Address *aUpstreamDnsServers, int aNumServers); 306 307 /** 308 * Initializes TREL on the given interface. 309 * 310 * After this call, TREL is ready to be enabled on the interface. Callers need to make sure TREL is disabled prior 311 * to this call. 312 */ 313 void otSysTrelInit(const char *aInterfaceName); 314 315 /** 316 * Deinitializes TREL. 317 * 318 * After this call, TREL is deinitialized. It's ready to be initialized on any given interface. Callers need to 319 * make sure TREL is disabled prior to this call. 320 */ 321 void otSysTrelDeinit(void); 322 323 /** 324 * Enables or disables the RCP restoration feature. 325 * 326 * @param[in] aEnabled TRUE to enable the RCP restoration feature, FALSE otherwise. 327 */ 328 void otSysSetRcpRestorationEnabled(bool aEnabled); 329 330 #ifdef __cplusplus 331 } // end of extern "C" 332 #endif 333 334 #endif // OPENTHREAD_SYSTEM_H_ 335