1 /** 2 * 3 * \file 4 * 5 * \brief WINC BSP API Declarations. 6 * 7 * Copyright (c) 2016-2017 Atmel Corporation. All rights reserved. 8 * 9 * \asf_license_start 10 * 11 * \page License 12 * 13 * Redistribution and use in source and binary forms, with or without 14 * modification, are permitted provided that the following conditions are met: 15 * 16 * 1. Redistributions of source code must retain the above copyright notice, 17 * this list of conditions and the following disclaimer. 18 * 19 * 2. Redistributions in binary form must reproduce the above copyright notice, 20 * this list of conditions and the following disclaimer in the documentation 21 * and/or other materials provided with the distribution. 22 * 23 * 3. The name of Atmel may not be used to endorse or promote products derived 24 * from this software without specific prior written permission. 25 * 26 * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED 27 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 28 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 29 * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR 30 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 34 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 35 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36 * POSSIBILITY OF SUCH DAMAGE. 37 * 38 * \asf_license_stop 39 * 40 */ 41 42 /** \defgroup nm_bsp BSP 43 */ 44 /**@defgroup BSPDefine Defines 45 * @ingroup nm_bsp 46 * @{ 47 */ 48 #ifndef _NM_BSP_H_ 49 #define _NM_BSP_H_ 50 51 #define NMI_API 52 /*!< 53 * Attribute used to define memory section to map Functions in host memory. 54 */ 55 #define CONST const 56 57 /*!< 58 * Used for code portability. 59 */ 60 61 #ifndef NULL 62 #define NULL ((void*)0) 63 #endif 64 /*!< 65 * Void Pointer to '0' in case of NULL is not defined. 66 */ 67 68 69 #define BSP_MIN(x,y) ((x)>(y)?(y):(x)) 70 /*!< 71 * Computes the minimum of \b x and \b y. 72 */ 73 74 //@} 75 76 /**@defgroup DataT DataTypes 77 * @ingroup nm_bsp 78 * @{ 79 */ 80 81 /*! 82 * @typedef void (*tpfNmBspIsr) (void); 83 * @brief Pointer to function.\n 84 * Used as a data type of ISR function registered by \ref nm_bsp_register_isr 85 * @return None 86 */ 87 typedef void (*tpfNmBspIsr)(void); 88 /*! 89 * @ingroup DataTypes 90 * @typedef unsigned char uint8; 91 * @brief Range of values between 0 to 255 92 */ 93 typedef unsigned char uint8; 94 95 /*! 96 * @ingroup DataTypes 97 * @typedef unsigned short uint16; 98 * @brief Range of values between 0 to 65535 99 */ 100 typedef unsigned short uint16; 101 102 /*! 103 * @ingroup Data Types 104 * @typedef unsigned long uint32; 105 * @brief Range of values between 0 to 4294967295 106 */ 107 typedef unsigned long uint32; 108 /*! 109 * @ingroup Data Types 110 * @typedef signed char sint8; 111 * @brief Range of values between -128 to 127 112 */ 113 typedef signed char sint8; 114 115 /*! 116 * @ingroup DataTypes 117 * @typedef signed short sint16; 118 * @brief Range of values between -32768 to 32767 119 */ 120 typedef signed short sint16; 121 122 /*! 123 * @ingroup DataTypes 124 * @typedef signed long sint32; 125 * @brief Range of values between -2147483648 to 2147483647 126 */ 127 128 typedef signed long sint32; 129 //@} 130 131 #ifndef CORTUS_APP 132 133 134 #ifdef __cplusplus 135 extern "C"{ 136 #endif 137 138 /** \defgroup BSPAPI Function 139 * @ingroup nm_bsp 140 */ 141 142 143 /** @defgroup NmBspInitFn nm_bsp_init 144 * @ingroup BSPAPI 145 * 146 * Initialization for BSP (<strong>B</strong>oard <strong>S</strong>upport <strong>P</strong>ackage) such as Reset and Chip Enable Pins for WINC, delays, 147 * register ISR, enable/disable IRQ for WINC, ...etc. You must use this function in the head of your application to 148 * enable WINC and Host Driver to communicate with each other. 149 */ 150 /**@{*/ 151 /*! 152 * @fn sint8 nm_bsp_init(void); 153 * @brief This function is used to initialize the <strong>B</strong>oard <strong>S</strong>upport <strong>P</strong>ackage <strong>(BSP)</strong> in order to prepare the WINC 154 * before it start working. 155 * 156 * The nm_bsp_init function is the first function that should be called at the beginning of 157 * every application to initialize the BSP and the WINC board. Otherwise, the rest of the BSP function 158 * calls will return with failure. This function should also be called after the WINC has been switched off with 159 * a successful call to "nm_bsp_deinit" in order to reinitialize the BSP before the user can use any of the WINC API 160 * functions again. After the function initialize the WINC. Hard reset must be applied to start the WINC board. 161 * @note Implementation of this function is host dependent. 162 * @warning inappropriate use of this function will lead to unavailability of host-chip communication.\n 163 * 164 * @see nm_bsp_deinit, nm_bsp_reset 165 * @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. 166 167 */ 168 sint8 nm_bsp_init(void); 169 /**@}*/ 170 171 172 /** @defgroup NmBspDeinitFn nm_bsp_deinit 173 * @ingroup BSPAPI 174 * De-initialization for BSP ((<strong>B</strong>oard <strong>S</strong>upport <strong>P</strong>ackage)). This function should be called only after 175 * a successful call to nm_bsp_init. 176 */ 177 /**@{*/ 178 /*! 179 * @fn sint8 nm_bsp_deinit(void); 180 * @pre The BSP should be initialized through \ref nm_bsp_init first. 181 * @brief This function is used to de-initialize the BSP and turn off the WINC board. 182 * 183 * The nm_bsp_deinit is the last function that should be called after the application has finished and before the WINC is switched 184 * off. The function call turns off the WINC board by setting CHIP_EN and RESET_N signals low.Every function call of "nm_bsp_init" should 185 * be matched with a call to nm_bsp_deinit. Failure to do so may result in the WINC consuming higher power than expected. 186 * @note Implementation of this function is host dependent. 187 * @warning misuse may lead to unknown behavior in case of soft reset.\n 188 * @see nm_bsp_init 189 * @return The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise. 190 191 */ 192 sint8 nm_bsp_deinit(void); 193 /**@}*/ 194 195 196 /** @defgroup NmBspResetFn nm_bsp_reset 197 * @ingroup BSPAPI 198 * Resetting WINC1500 SoC by setting CHIP_EN and RESET_N signals low, then after specific delay the function will put CHIP_EN high then RESET_N high, 199 * for the timing between signals please review the WINC data-sheet 200 */ 201 /**@{*/ 202 /*! 203 * @fn void nm_bsp_reset(void); 204 * @param [in] None 205 * @brief Applies a hardware reset to the WINC board. 206 * The "nm_bsp_reset" is used to apply a hard reset to the WINC board by setting CHIP_EN and RESET_N signals low, then after specific delay 207 * the function will put CHIP_EN high then RESET_N high, for the detailed timing between signals please review the WINC data-sheet. After a 208 * successful call, the WINC board firmware will kick off to load and kick off the WINC firmware. This function should be called to reset the 209 * WINC firmware after the BSP is initialized and before the start of any communication with WINC board. Calling this function at any other time 210 * will result in losing the state and connections saved in the WINC board and starting again from the initial state. The host driver will need 211 * to be de-initialized before calling nm_bsp_reset and initialized again after it using the " m2m_wifi_(de)init". 212 * @pre Initialize \ref nm_bsp_init first 213 * @note Implementation of this function is host dependent and called by HIF layer. 214 * @warning Calling this function will drop any connection and internal state saved on the WINC firmware. 215 * @see nm_bsp_init, m2m_wifi_init, m2m_wifi_deinit 216 * @return None 217 218 */ 219 void nm_bsp_reset(void); 220 /**@}*/ 221 222 223 /** @defgroup NmBspSleepFn nm_bsp_sleep 224 * @ingroup BSPAPI 225 * Sleep in units of milliseconds.\n 226 * This function used by HIF Layer according to different situations. 227 */ 228 /**@{*/ 229 /*! 230 * @fn void nm_bsp_sleep(uint32); 231 * @brief Used to put the host to sleep for the specified duration. 232 * Forcing the host to sleep for extended period may lead to host not being able to respond to WINC board events.It's important to 233 * be considerate while choosing the sleep period. 234 * @param [in] u32TimeMsec 235 * Time unit in milliseconds 236 * @pre Initialize \ref nm_bsp_init first 237 * @warning Maximum value must nor exceed 4294967295 milliseconds which is equal to 4294967.295 seconds.\n 238 * @note Implementation of this function is host dependent. 239 * @see nm_bsp_init 240 * @return None 241 */ 242 void nm_bsp_sleep(uint32 u32TimeMsec); 243 /**@}*/ 244 245 246 /** @defgroup NmBspRegisterFn nm_bsp_register_isr 247 * @ingroup BSPAPI 248 * Register ISR (Interrupt Service Routine) in the initialization of HIF (Host Interface) Layer. 249 * When the interrupt trigger the BSP layer should call the pfisr function once inside the interrupt. 250 */ 251 /**@{*/ 252 /*! 253 * @fn void nm_bsp_register_isr(tpfNmBspIsr); 254 * @param [in] tpfNmBspIsr pfIsr 255 * Pointer to ISR handler in HIF 256 * @brief Register the host interface interrupt service routine. 257 * WINC board utilize SPI interface to communicate with the host. This function register the SPI interrupt the notify 258 * the host whenever there is an outstanding message from the WINC board. The function should be called during the initialization 259 * of the host interface. It an internal driver function and shouldn't be called by the application. 260 * @warning Make sure that ISR for IRQ pin for WINC is disabled by default in your implementation. 261 * @note Implementation of this function is host dependent and called by HIF layer. 262 * @see tpfNmBspIsr 263 * @return None 264 265 */ 266 void nm_bsp_register_isr(tpfNmBspIsr pfIsr); 267 /**@}*/ 268 269 270 /** @defgroup NmBspInterruptCtrl nm_bsp_interrupt_ctrl 271 * @ingroup BSPAPI 272 * Synchronous enable/disable interrupts function 273 */ 274 /**@{*/ 275 /*! 276 * @fn void nm_bsp_interrupt_ctrl(uint8); 277 * @pre The interrupt must be registered using nm_bsp_register_isr first. 278 * @brief Enable/Disable interrupts 279 * This function can be used to enable/disable the WINC to host interrupt as the depending on how the driver is implemented. 280 * It an internal driver function and shouldn't be called by the application. 281 * @param [in] u8Enable 282 * '0' disable interrupts. '1' enable interrupts 283 * @see tpfNmBspIsr, nm_bsp_register_isr 284 * @note Implementation of this function is host dependent and called by HIF layer. 285 * @return None 286 287 */ 288 void nm_bsp_interrupt_ctrl(uint8 u8Enable); 289 /**@}*/ 290 291 #ifdef __cplusplus 292 } 293 #endif 294 295 #endif 296 297 #ifdef _NM_BSP_BIG_END 298 #define NM_BSP_B_L_32(x) \ 299 ((((x) & 0x000000FF) << 24) + \ 300 (((x) & 0x0000FF00) << 8) + \ 301 (((x) & 0x00FF0000) >> 8) + \ 302 (((x) & 0xFF000000) >> 24)) 303 #define NM_BSP_B_L_16(x) \ 304 ((((x) & 0x00FF) << 8) + \ 305 (((x) & 0xFF00) >> 8)) 306 #else 307 #define NM_BSP_B_L_32(x) (x) 308 #define NM_BSP_B_L_16(x) (x) 309 #endif 310 311 312 #endif /*_NM_BSP_H_*/ 313
