nm_bsp.h

00001 /**
00002  *
00003  * \file
00004  *
00005  * \brief WINC BSP API Declarations.
00006  *
00007  * Copyright (c) 2015 Atmel Corporation. All rights reserved.
00008  *
00009  * \asf_license_start
00010  *
00011  * \page License
00012  *
00013  * Redistribution and use in source and binary forms, with or without
00014  * modification, are permitted provided that the following conditions are met:
00015  *
00016  * 1. Redistributions of source code must retain the above copyright notice,
00017  *    this list of conditions and the following disclaimer.
00018  *
00019  * 2. Redistributions in binary form must reproduce the above copyright notice,
00020  *    this list of conditions and the following disclaimer in the documentation
00021  *    and/or other materials provided with the distribution.
00022  *
00023  * 3. The name of Atmel may not be used to endorse or promote products derived
00024  *    from this software without specific prior written permission.
00025  *
00026  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED
00027  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00028  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00029  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR
00030  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00031  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00032  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00033  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
00034  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00035  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00036  * POSSIBILITY OF SUCH DAMAGE.
00037  *
00038  * \asf_license_stop
00039  *
00040  */
00041  
00042 /** \defgroup nm_bsp BSP
00043  */
00044 /**@defgroup  BSPDefine Defines
00045  * @ingroup nm_bsp
00046  * @{
00047  */
00048 #ifndef _NM_BSP_H_
00049 #define _NM_BSP_H_
00050 
00051 #define CONF_WINC_USE_SPI               (1)//added by Tsungta original from conf_winc.h
00052 #define CONF_WINC_DEBUG                 (0)//added by Tsungta original from conf_winc.h
00053 #define CONF_WINC_PRINTF                printf//added by Tsungta original from conf_winc.h
00054 #define NM_EDGE_INTERRUPT               (1)//added by Tsungta original from nm_bsp_samd21.h
00055 
00056 #define NMI_API
00057 /*!< 
00058 *        Attribute used to define memory section to map Functions in host memory.
00059 */
00060 #define CONST const
00061 
00062 /*!< 
00063 *     Used for code portability.
00064 */
00065 
00066 #ifndef NULL
00067 #define NULL ((void*)0)
00068 #endif
00069 /*!< 
00070 *    Void Pointer to '0' in case of NULL is not defined. 
00071 */
00072 
00073 
00074 #define BSP_MIN(x,y) ((x)>(y)?(y):(x))
00075 /*!< 
00076 *     Computes the minimum of \b x and \b y.
00077 */
00078 
00079  //@}
00080 
00081 /**@defgroup  DataT  DataTypes
00082  * @ingroup nm_bsp
00083  * @{
00084  */
00085  
00086 /*!
00087  * @typedef      void (*tpfNmBspIsr) (void);
00088  * @brief           Pointer to function.\n
00089  *                     Used as a data type of ISR function registered by \ref nm_bsp_register_isr
00090  * @return         None
00091  */
00092 typedef void (*tpfNmBspIsr)(void);
00093   /*!
00094  * @ingroup DataTypes
00095  * @typedef      unsigned char  uint8;
00096  * @brief        Range of values between 0 to 255
00097  */
00098 typedef unsigned char   uint8;
00099 
00100  /*!
00101  * @ingroup DataTypes
00102  * @typedef      unsigned short uint16;
00103  * @brief        Range of values between 0 to 65535
00104  */
00105 typedef unsigned short  uint16;
00106 
00107  /*!
00108  * @ingroup Data Types
00109  * @typedef      unsigned long  uint32;
00110  * @brief        Range of values between 0 to 4294967295
00111  */ 
00112 typedef unsigned long   uint32;
00113   /*!
00114  * @ingroup Data Types
00115  * @typedef      signed char        sint8;
00116  * @brief        Range of values between -128 to 127
00117  */
00118 typedef signed char     sint8;
00119 
00120  /*!
00121  * @ingroup DataTypes
00122  * @typedef      signed short   sint16;
00123  * @brief        Range of values between -32768 to 32767
00124  */
00125 typedef signed short    sint16;
00126 
00127   /*!
00128  * @ingroup DataTypes
00129  * @typedef      signed long        sint32;
00130  * @brief        Range of values between -2147483648 to 2147483647
00131  */
00132 
00133 typedef signed long     sint32;
00134  //@}
00135 
00136 #ifndef CORTUS_APP
00137 
00138 
00139 #ifdef __cplusplus
00140 extern "C"{
00141 #endif
00142 
00143 /** \defgroup BSPAPI Function
00144  *   @ingroup nm_bsp
00145  */
00146 
00147 
00148 /** @defgroup NmBspInitFn nm_bsp_init
00149  *  @ingroup BSPAPI
00150  *
00151  *  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,
00152  *  register ISR, enable/disable IRQ for WINC, ...etc. You must use this function in the head of your application to 
00153  *  enable WINC and Host Driver to communicate with each other. 
00154  */
00155  /**@{*/
00156 /*!
00157  * @fn           sint8 nm_bsp_init(void);
00158  * @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
00159  *               before it start working.
00160  *
00161  *               The nm_bsp_init function is the first function that should be called at the beginning of
00162  *               every application to initialize the BSP and the WINC board. Otherwise, the rest of the BSP function
00163  *               calls will return with failure. This function should also be called after the WINC has been switched off with 
00164  *               a successful call to "nm_bsp_deinit" in order to reinitialize the BSP before the user can use any of the WINC API
00165  *               functions again. After the function initialize the WINC. Hard reset must be applied to start the WINC board.
00166  * @note         Implementation of this function is host dependent.
00167  * @warning      inappropriate use of this function will lead to unavailability of host-chip communication.\n
00168  *  
00169  * @see          nm_bsp_deinit, nm_bsp_reset
00170  * @return       The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
00171 
00172  */
00173 sint8 nm_bsp_init(void);
00174  /**@}*/
00175 
00176  
00177  /** @defgroup NmBspDeinitFn nm_bsp_deinit
00178  *    @ingroup BSPAPI
00179  *       De-initialization for BSP ((<strong>B</strong>oard <strong>S</strong>upport <strong>P</strong>ackage)). This function should be called only after
00180  *       a successful call to nm_bsp_init. 
00181  */
00182  /**@{*/
00183 /*!
00184  * @fn           sint8 nm_bsp_deinit(void);
00185  * @pre          The BSP should be initialized through \ref nm_bsp_init first.
00186  * @brief        This function is used to de-initialize the BSP and turn off the WINC board.
00187  *               
00188  *               The nm_bsp_deinit is the last function that should be called after the application has finished and before the WINC is switched 
00189  *               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
00190  *               be matched with a call to nm_bsp_deinit. Failure to do so may result in the WINC consuming higher power than expected. 
00191  * @note         Implementation of this function is host dependent.
00192  * @warning      misuse may lead to unknown behavior in case of soft reset.\n
00193  * @see          nm_bsp_init               
00194  * @return      The function returns @ref M2M_SUCCESS for successful operations and a negative value otherwise.
00195 
00196  */
00197 sint8 nm_bsp_deinit(void);
00198  /**@}*/
00199 
00200  
00201 /** @defgroup NmBspResetFn  nm_bsp_reset
00202 *     @ingroup BSPAPI
00203 *      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,
00204 *      for the timing between signals please review the WINC data-sheet
00205 */
00206 /**@{*/
00207  /*!
00208  * @fn           void nm_bsp_reset(void);    
00209  * @param [in]   None
00210  * @brief        Applies a hardware reset to the WINC board.
00211  *               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
00212  *               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
00213  *               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 
00214  *               WINC firmware after the BSP is initialized and before the start of any communication with WINC board. Calling this function at any other time
00215  *               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 
00216  *               to be de-initialized before calling nm_bsp_reset and initialized again after it using the " m2m_wifi_(de)init". 
00217  * @pre          Initialize \ref nm_bsp_init first
00218  * @note         Implementation of this function is host dependent and called by HIF layer.
00219  * @warning      Calling this function will drop any connection and internal state saved on the WINC firmware.
00220  * @see          nm_bsp_init, m2m_wifi_init,  m2m_wifi_deinit
00221  * @return       None
00222 
00223  */
00224 void nm_bsp_reset(void);
00225  /**@}*/
00226 
00227  
00228 /** @defgroup NmBspSleepFn nm_bsp_sleep
00229 *     @ingroup BSPAPI
00230 *     Sleep in units of milliseconds.\n
00231 *    This function used by HIF Layer according to different situations. 
00232 */
00233 /**@{*/
00234 /*!
00235  * @fn           void nm_bsp_sleep(uint32);
00236  * @brief        Used to put the host to sleep for the specified duration.
00237  *               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
00238  *               be considerate while choosing the sleep period. 
00239  * @param [in]   u32TimeMsec
00240  *               Time unit in milliseconds
00241  * @pre          Initialize \ref nm_bsp_init first
00242  * @warning      Maximum value must nor exceed 4294967295 milliseconds which is equal to 4294967.295 seconds.\n
00243  * @note         Implementation of this function is host dependent.
00244  * @see           nm_bsp_init               
00245  * @return       None
00246  */
00247 void nm_bsp_sleep(uint32 u32TimeMsec);
00248 /**@}*/
00249 
00250   
00251 /** @defgroup NmBspRegisterFn nm_bsp_register_isr
00252 *     @ingroup BSPAPI
00253 *   Register ISR (Interrupt Service Routine) in the initialization of HIF (Host Interface) Layer. 
00254 *   When the interrupt trigger the BSP layer should call the pfisr function once inside the interrupt.
00255 */
00256 /**@{*/
00257 /*!
00258  * @fn           void nm_bsp_register_isr(tpfNmBspIsr);
00259  * @param [in]   tpfNmBspIsr  pfIsr
00260  *               Pointer to ISR handler in HIF
00261  * @brief        Register the host interface interrupt service routine.
00262  *               WINC board utilize SPI interface to communicate with the host. This function register the SPI interrupt the notify
00263  *               the host whenever there is an outstanding message from the WINC board. The function should be called during the initialization
00264  *               of the host interface. It an internal driver function and shouldn't be called by the application. 
00265  * @warning      Make sure that ISR for IRQ pin for WINC is disabled by default in your implementation.
00266  * @note         Implementation of this function is host dependent and called by HIF layer.
00267  * @see          tpfNmBspIsr
00268  * @return       None
00269 
00270  */
00271 void nm_bsp_register_isr(tpfNmBspIsr pfIsr);
00272 /**@}*/
00273 
00274   
00275 /** @defgroup NmBspInterruptCtrl nm_bsp_interrupt_ctrl
00276 *     @ingroup BSPAPI
00277 *    Synchronous enable/disable interrupts function
00278 */
00279 /**@{*/
00280 /*!
00281  * @fn           void nm_bsp_interrupt_ctrl(uint8);
00282  * @pre          The interrupt must be registered using nm_bsp_register_isr first.
00283  * @brief        Enable/Disable interrupts
00284  *               This function can be used to enable/disable the WINC to host interrupt as the depending on how the driver is implemented.
00285  *               It an internal driver function and shouldn't be called by the application.
00286  * @param [in]   u8Enable
00287  *               '0' disable interrupts. '1' enable interrupts 
00288  * @see          tpfNmBspIsr, nm_bsp_register_isr     
00289  * @note         Implementation of this function is host dependent and called by HIF layer.
00290  * @return       None
00291 
00292  */
00293 void nm_bsp_interrupt_ctrl(uint8 u8Enable);
00294   /**@}*/
00295 
00296 #ifdef __cplusplus
00297 }
00298 #endif
00299 
00300 #endif
00301 
00302 #ifdef _NM_BSP_BIG_END
00303 #define NM_BSP_B_L_32(x) \
00304 ((((x) & 0x000000FF) << 24) + \
00305 (((x) & 0x0000FF00) << 8)  + \
00306 (((x) & 0x00FF0000) >> 8)   + \
00307 (((x) & 0xFF000000) >> 24))
00308 #define NM_BSP_B_L_16(x) \
00309 ((((x) & 0x00FF) << 8) + \
00310 (((x)  & 0xFF00) >> 8))
00311 #else
00312 #define NM_BSP_B_L_32(x)  (x)
00313 #define NM_BSP_B_L_16(x)  (x)
00314 #endif
00315 
00316 
00317 #endif  /*_NM_BSP_H_*/
00318 
00319