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