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 includes platform abstractions for miscellaneous behaviors. 33 */ 34 35 #ifndef OPENTHREAD_PLATFORM_MISC_H_ 36 #define OPENTHREAD_PLATFORM_MISC_H_ 37 38 #include <stdint.h> 39 40 #include <openthread/instance.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 /** 47 * @addtogroup plat-misc 48 * 49 * @brief 50 * This module includes platform abstractions for miscellaneous behaviors. 51 * 52 * @{ 53 * 54 */ 55 56 /** 57 * Performs a software reset on the platform, if supported. 58 * 59 * @param[in] aInstance The OpenThread instance structure. 60 * 61 */ 62 void otPlatReset(otInstance *aInstance); 63 64 /** 65 * Performs a hardware reset on the platform to launch bootloader mode, if supported. 66 * 67 * Used when `OPENTHREAD_CONFIG_PLATFORM_BOOTLOADER_MODE_ENABLE` is enabled. 68 * 69 * @param[in] aInstance The OpenThread instance structure. 70 * 71 * @retval OT_ERROR_NONE Reset to bootloader successfully. 72 * @retval OT_ERROR_BUSY Failed due to another operation is ongoing. 73 * @retval OT_ERROR_NOT_CAPABLE Not capable of resetting to bootloader. 74 * 75 */ 76 otError otPlatResetToBootloader(otInstance *aInstance); 77 78 /** 79 * Enumeration of possible reset reason codes. 80 * 81 * These are in the same order as the Spinel reset reason codes. 82 * 83 */ 84 typedef enum 85 { 86 OT_PLAT_RESET_REASON_POWER_ON = 0, 87 OT_PLAT_RESET_REASON_EXTERNAL = 1, 88 OT_PLAT_RESET_REASON_SOFTWARE = 2, 89 OT_PLAT_RESET_REASON_FAULT = 3, 90 OT_PLAT_RESET_REASON_CRASH = 4, 91 OT_PLAT_RESET_REASON_ASSERT = 5, 92 OT_PLAT_RESET_REASON_OTHER = 6, 93 OT_PLAT_RESET_REASON_UNKNOWN = 7, 94 OT_PLAT_RESET_REASON_WATCHDOG = 8, 95 96 OT_PLAT_RESET_REASON_COUNT, 97 } otPlatResetReason; 98 99 /** 100 * Returns the reason for the last platform reset. 101 * 102 * @param[in] aInstance The OpenThread instance structure. 103 * 104 */ 105 otPlatResetReason otPlatGetResetReason(otInstance *aInstance); 106 107 /** 108 * Provides a platform specific implementation for assert. 109 * 110 * @param[in] aFilename The name of the file where the assert occurred. 111 * @param[in] aLineNumber The line number in the file where the assert occurred. 112 * 113 */ 114 void otPlatAssertFail(const char *aFilename, int aLineNumber); 115 116 /** 117 * Performs a platform specific operation to wake the host MCU. 118 * This is used only for NCP configurations. 119 * 120 */ 121 void otPlatWakeHost(void); 122 123 /** 124 * Enumeration of micro-controller's power states. 125 * 126 * These values are used for NCP configuration when `OPENTHREAD_CONFIG_NCP_ENABLE_MCU_POWER_STATE_CONTROL` is enabled. 127 * 128 * The power state specifies the desired power state of NCP's micro-controller (MCU) when the underlying platform's 129 * operating system enters idle mode (i.e., all active tasks/events are processed and the MCU can potentially enter a 130 * energy-saving power state). 131 * 132 * The power state primarily determines how the host should interact with the NCP and whether the host needs an 133 * external trigger (a "poke") to NCP before it can communicate with the NCP or not. 134 * 135 * After a reset, the MCU power state MUST be `OT_PLAT_POWER_STATE_ON`. 136 * 137 */ 138 typedef enum 139 { 140 /** 141 * NCP's MCU stays on and active all the time. 142 * 143 * When the NCP's desired power state is set to `ON`, host can send messages to NCP without requiring any "poke" or 144 * external triggers. 145 * 146 * @note The `ON` power state only determines the MCU's power mode and is not related to radio's state. 147 * 148 */ 149 OT_PLAT_MCU_POWER_STATE_ON = 0, 150 151 /** 152 * NCP's MCU can enter low-power (energy-saving) state. 153 * 154 * When the NCP's desired power state is set to `LOW_POWER`, host is expected to "poke" the NCP (e.g., an external 155 * trigger like an interrupt) before it can communicate with the NCP (send a message to the NCP). The "poke" 156 * mechanism is determined by the platform code (based on NCP's interface to the host). 157 * 158 * While power state is set to `LOW_POWER`, NCP can still (at any time) send messages to host. Note that receiving 159 * a message from the NCP does NOT indicate that the NCP's power state has changed, i.e., host is expected to 160 * continue to "poke" when it wants to talk to the NCP until the power state is explicitly changed (by a successful 161 * call to `otPlatSetMcuPowerState()` changing the state to `ON`). 162 * 163 * @note The `LOW_POWER` power state only determines the MCU's power mode and is not related to radio's state 164 * (radio is managed by OpenThread core and device role, e.g., device being sleepy or not. 165 * 166 */ 167 OT_PLAT_MCU_POWER_STATE_LOW_POWER = 1, 168 169 /** 170 * NCP is fully off. 171 * 172 * An NCP hardware reset (via a RESET pin) is required to bring the NCP back to `SPINEL_MCU_POWER_STATE_ON`. 173 * RAM is not retained after reset. 174 * 175 */ 176 OT_PLAT_MCU_POWER_STATE_OFF = 2, 177 } otPlatMcuPowerState; 178 179 /** 180 * Sets the desired MCU power state. 181 * 182 * This is only applicable and used for NCP configuration when `OPENTHREAD_CONFIG_NCP_ENABLE_MCU_POWER_STATE_CONTROL` 183 * is enabled. 184 * 185 * @param[in] aInstance A pointer to OpenThread instance. 186 * @param[in] aState The new MCU power state. 187 * 188 * @retval OT_ERROR_NONE The power state updated successfully. 189 * @retval OT_ERROR_FAILED The given MCU power state is not supported by the platform. 190 * 191 */ 192 otError otPlatSetMcuPowerState(otInstance *aInstance, otPlatMcuPowerState aState); 193 194 /** 195 * Gets the current desired MCU power state. 196 * 197 * This is only applicable and used for NCP configuration when `OPENTHREAD_CONFIG_NCP_ENABLE_MCU_POWER_STATE_CONTROL` 198 * is enabled. 199 * 200 * After a reset, the power state MUST return `OT_PLAT_POWER_STATE_ON`. During operation, power state SHOULD only 201 * change through an explicit successful call to `otPlatSetMcuPowerState()`. 202 * 203 * @param[in] aInstance A pointer to OpenThread instance. 204 * 205 * @returns The current power state. 206 * 207 */ 208 otPlatMcuPowerState otPlatGetMcuPowerState(otInstance *aInstance); 209 210 /** 211 * @} 212 * 213 */ 214 215 #ifdef __cplusplus 216 } // extern "C" 217 #endif 218 219 #endif // OPENTHREAD_PLATFORM_MISC_H_ 220
