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  * This function 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  * This function 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  * This function 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  * This function 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  * This function 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  * This function 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