SPIRIT_Irq.h

00001 /**
00002   ******************************************************************************
00003  * @file    SPIRIT_Irq.h
00004   * @author  VMA division - AMS
00005   * @version 3.2.2
00006   * @date    08-July-2015
00007  * @brief   Configuration and management of SPIRIT IRQs.
00008   * 
00009  * @details
00010  *
00011  * On the Spirit side specific IRQs can be enabled by setting a specific bitmask.
00012  * The Spirit libraries allow the user to do this in two different ways:
00013  * <ul>
00014  *
00015  * <li>The first enables the IRQs one by one, i.e. using an SPI transaction for each
00016  * IRQ to enable.
00017  *
00018  * <b>Example:</b>
00019  * @code
00020  *
00021  *  SpiritIrqDeInit(NULL);                // this call is used to reset the IRQ mask registers
00022  *  SpiritIrq(RX_DATA_READY , S_ENABLE);
00023  *  SpiritIrq(VALID_SYNC , S_ENABLE);
00024  *  SpiritIrq(RX_TIMEOUT , S_ENABLE);
00025  *
00026  * @endcode
00027  *
00028  * </li>
00029  *
00030  * <li>The second strategy is to set the IRQ bitfields structure. So, during the initialization the user
00031  * has to fill the @ref SpiritIrqs structure setting to one the single field related to the IRQ he
00032  * wants to enable, and to zero the single field related to all the IRQs he wants to disable.
00033  *
00034  * <b>Example:</b>
00035  * @code
00036  *
00037  *  SpiritIrqs irqMask;
00038  *
00039  *  ...
00040  *
00041  *  SpiritIrqDeInit(&irqMask);                // this call is used to reset the IRQ mask registers
00042  *                                            // and to set to 0x00000000 the irq mask in order to disable
00043  *                                            // all IRQs (disabled by default on startup)
00044  *  irqMask.IRQ_RX_DATA_READY = 1;
00045  *  irqMask.IRQ_VALID_SYNC = 1;
00046  *  irqMask.IRQ_RX_TIMEOUT = 1;
00047  *
00048  *  ...
00049  * @endcode
00050  * </li>
00051  * </ul>
00052  *
00053  * The most applications will require a Spirit IRQ notification on an microcontroller EXTI line.
00054  * Then, the user can check which IRQ has been raised using two different ways.
00055  *
00056  * On the ISR of the EXTI line phisically linked to the Spirit pin configured for IRQ:
00057  *
00058  * <ul>
00059  * <li> Check <b>only one</b> Spirit IRQ (because the Spirit IRQ status register automatically blanks itself
00060  * after an SPI reading) into the ISR.
00061  *
00062  * <b>Example:</b>
00063  * @code
00064  *
00065  *  if(SpiritIrqCheckFlag(RX_DATA_READY))
00066  *  {
00067  *          // do something...
00068  *  }
00069  *
00070  * @endcode
00071  * </li>
00072  *
00073  * <li> Check more than one Spirit IRQ status by storing the entire IRQ status registers into a bitfields <i>@ref SpiritIrqs</i> structure
00074  * and then check the interested bits.
00075  *
00076  * <b>Example:</b>
00077  * @code
00078  *
00079  *  SpiritIrqGetStatus(&irqStatus);
00080  *
00081  *  if(irqStatus.IRQ_RX_DATA_READY)
00082  *  {
00083  *          // do something...
00084  *  }
00085  *  if(irqStatus.IRQ_VALID_SYNC)
00086  *  {
00087  *         // do something...
00088  *  }
00089  *  if(irqStatus.RX_TIMEOUT)
00090  *  {
00091  *         // do something...
00092  *  }
00093  *
00094  * @endcode
00095  * </li>
00096  * </ul>
00097  *
00098 
00099   * @attention
00100   *
00101   * <h2><center>&copy; COPYRIGHT(c) 2015 STMicroelectronics</center></h2>
00102  *
00103   * Redistribution and use in source and binary forms, with or without modification,
00104   * are permitted provided that the following conditions are met:
00105   *   1. Redistributions of source code must retain the above copyright notice,
00106   *      this list of conditions and the following disclaimer.
00107   *   2. Redistributions in binary form must reproduce the above copyright notice,
00108   *      this list of conditions and the following disclaimer in the documentation
00109   *      and/or other materials provided with the distribution.
00110   *   3. Neither the name of STMicroelectronics nor the names of its contributors
00111   *      may be used to endorse or promote products derived from this software
00112   *      without specific prior written permission.
00113   *
00114   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00115   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00116   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00117   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
00118   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00119   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00120   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00121   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00122   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
00123   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00124   *
00125   ******************************************************************************
00126  */
00127 
00128 /* Define to prevent recursive inclusion -------------------------------------*/
00129 #ifndef __SPIRIT1_IRQ_H
00130 #define __SPIRIT1_IRQ_H
00131 
00132 
00133 /* Includes ------------------------------------------------------------------*/
00134 
00135 #include "SPIRIT_Regs.h"
00136 #include "SPIRIT_Types.h"
00137 
00138 
00139 #ifdef __cplusplus
00140  extern "C" {
00141 #endif
00142 
00143 
00144 /**
00145  * @addtogroup SPIRIT_Libraries
00146  * @{
00147  */
00148 
00149 
00150 /**
00151  * @defgroup SPIRIT_Irq IRQ
00152  * @brief Configuration and management of SPIRIT IRQs.
00153  * @details See the file <i>@ref SPIRIT_Irq.h</i> for more details.
00154  * @{
00155  */
00156 
00157 /**
00158  * @defgroup Irq_Exported_Types IRQ Exported Types
00159  * @{
00160  */
00161 
00162 
00163 /**
00164  * @brief IRQ bitfield structure for SPIRIT. This structure is used to read or write the single IRQ bit.
00165  *        During the initialization the user has to fill this structure setting to one the single field related
00166  *        to the IRQ he wants to enable, and to zero the single field related to all the IRQs he wants to disable.
00167  *        The same structure can be used to retrieve all the IRQ events from the IRQ registers IRQ_STATUS[3:0],
00168  *        and read if one or more specific IRQ raised.
00169  * @note  The fields order in the structure depends on used endianness (little or big
00170  *        endian). The actual definition is valid ONLY for LITTLE ENDIAN mode. Be sure to
00171  *        change opportunely the fields order when use a different endianness.
00172  */
00173 typedef struct
00174 {
00175       SpiritFlagStatus  IRQ_SYNTH_LOCK_TIMEOUT:1;       /*!< IRQ: only for debug; LOCK state timeout */
00176       SpiritFlagStatus  IRQ_SYNTH_LOCK_STARTUP:1;       /*!< IRQ: only for debug; see CALIBR_START_COUNTER */
00177       SpiritFlagStatus  IRQ_SYNTH_CAL_TIMEOUT:1;        /*!< IRQ: only for debug; SYNTH calibration timeout */
00178       SpiritFlagStatus  IRQ_TX_START_TIME:1;            /*!< IRQ: only for debug; TX circuitry startup time; see TX_START_COUNTER */
00179       SpiritFlagStatus  IRQ_RX_START_TIME:1;            /*!< IRQ: only for debug; RX circuitry startup time; see TX_START_COUNTER */
00180       SpiritFlagStatus  IRQ_RX_TIMEOUT:1;               /*!< IRQ: RX operation timeout */
00181       SpiritFlagStatus  IRQ_AES_END:1;                  /*!< IRQ: AES End of operation */
00182       SpiritFlagStatus  reserved:1;                     /*!< Reserved bit */
00183 
00184       SpiritFlagStatus  IRQ_READY:1;                    /*!< IRQ: READY state */
00185       SpiritFlagStatus  IRQ_STANDBY_DELAYED:1;          /*!< IRQ: STANDBY state after MCU_CK_CONF_CLOCK_TAIL_X clock cycles */
00186       SpiritFlagStatus  IRQ_LOW_BATT_LVL:1;             /*!< IRQ: Battery level below threshold*/
00187       SpiritFlagStatus  IRQ_POR:1;                      /*!< IRQ: Power On Reset */
00188       SpiritFlagStatus  IRQ_BOR:1;                      /*!< IRQ: Brown out event (both accurate and inaccurate)*/
00189       SpiritFlagStatus  IRQ_LOCK:1;                     /*!< IRQ: LOCK state */
00190       SpiritFlagStatus  IRQ_PM_COUNT_EXPIRED:1;         /*!< IRQ: only for debug; Power Management startup timer expiration (see reg PM_START_COUNTER, 0xB5) */
00191       SpiritFlagStatus  IRQ_XO_COUNT_EXPIRED:1;         /*!< IRQ: only for debug; Crystal oscillator settling time counter expired */
00192 
00193       SpiritFlagStatus  IRQ_TX_FIFO_ALMOST_EMPTY:1;     /*!< IRQ: TX FIFO almost empty */
00194       SpiritFlagStatus  IRQ_RX_FIFO_ALMOST_FULL:1;      /*!< IRQ: RX FIFO almost full */
00195       SpiritFlagStatus  IRQ_RX_FIFO_ALMOST_EMPTY:1;     /*!< IRQ: RX FIFO almost empty  */
00196       SpiritFlagStatus  IRQ_MAX_BO_CCA_REACH:1;         /*!< IRQ: Max number of back-off during CCA */
00197       SpiritFlagStatus  IRQ_VALID_PREAMBLE:1;           /*!< IRQ: Valid preamble detected */
00198       SpiritFlagStatus  IRQ_VALID_SYNC:1;               /*!< IRQ: Sync word detected */
00199       SpiritFlagStatus  IRQ_RSSI_ABOVE_TH:1;            /*!< IRQ: RSSI above threshold */
00200       SpiritFlagStatus  IRQ_WKUP_TOUT_LDC:1;            /*!< IRQ: Wake-up timeout in LDC mode */
00201 
00202       SpiritFlagStatus  IRQ_RX_DATA_READY:1;            /*!< IRQ: RX data ready */
00203       SpiritFlagStatus  IRQ_RX_DATA_DISC:1;             /*!< IRQ: RX data discarded (upon filtering) */
00204       SpiritFlagStatus  IRQ_TX_DATA_SENT:1;             /*!< IRQ: TX data sent */
00205       SpiritFlagStatus  IRQ_MAX_RE_TX_REACH:1;          /*!< IRQ: Max re-TX reached */
00206       SpiritFlagStatus  IRQ_CRC_ERROR:1;                /*!< IRQ: CRC error */
00207       SpiritFlagStatus  IRQ_TX_FIFO_ERROR:1;            /*!< IRQ: TX FIFO underflow/overflow error */
00208       SpiritFlagStatus  IRQ_RX_FIFO_ERROR:1;            /*!< IRQ: RX FIFO underflow/overflow error */
00209       SpiritFlagStatus  IRQ_TX_FIFO_ALMOST_FULL:1;      /*!< IRQ: TX FIFO almost full */
00210 } SpiritIrqs;
00211 
00212 // betzw: uint32_t masks
00213 #define IRQ_TX_FIFO_ALMOST_EMPTY_MASK   (0x00010000) /* (1<<16) */
00214 #define IRQ_RX_FIFO_ALMOST_FULL_MASK    (0x00020000) /* (1<<17) */
00215 #define IRQ_VALID_SYNC_MASK             (0x00200000) /* (1<<21) */
00216 #define IRQ_RX_DATA_READY_MASK          (0x01000000) /* (1<<24) */
00217 #define IRQ_RX_DATA_DISC_MASK           (0x02000000) /* (1<<25) */
00218 #define IRQ_TX_DATA_SENT_MASK           (0x04000000) /* (1<<26) */
00219 #define IRQ_TX_FIFO_ERROR_MASK          (0x20000000) /* (1<<29) */
00220 #define IRQ_RX_FIFO_ERROR_MASK          (0x40000000) /* (1<<30) */
00221 
00222 /**
00223  * @brief  IRQ list enumeration for SPIRIT. This enumeration type can be used to address a
00224  *         specific IRQ.
00225  */
00226 typedef enum
00227 {
00228   RX_DATA_READY  = 0x00000001,           /*!< IRQ: RX data ready */
00229   RX_DATA_DISC  = 0x00000002,            /*!< IRQ: RX data discarded (upon filtering) */
00230   TX_DATA_SENT  = 0x00000004,            /*!< IRQ: TX data sent */
00231   MAX_RE_TX_REACH  = 0x00000008,         /*!< IRQ: Max re-TX reached */
00232   CRC_ERROR  = 0x00000010,               /*!< IRQ: CRC error */
00233   TX_FIFO_ERROR  = 0x00000020,           /*!< IRQ: TX FIFO underflow/overflow error */
00234   RX_FIFO_ERROR  = 0x00000040,           /*!< IRQ: RX FIFO underflow/overflow error */
00235   TX_FIFO_ALMOST_FULL  = 0x00000080,     /*!< IRQ: TX FIFO almost full */
00236   TX_FIFO_ALMOST_EMPTY  = 0x00000100,    /*!< IRQ: TX FIFO almost empty */
00237   RX_FIFO_ALMOST_FULL  = 0x00000200,     /*!< IRQ: RX FIFO almost full */
00238   RX_FIFO_ALMOST_EMPTY  = 0x00000400,    /*!< IRQ: RX FIFO almost empty  */
00239   MAX_BO_CCA_REACH  = 0x00000800,        /*!< IRQ: Max number of back-off during CCA */
00240   VALID_PREAMBLE  = 0x00001000,          /*!< IRQ: Valid preamble detected */
00241   VALID_SYNC  = 0x00002000,              /*!< IRQ: Sync word detected */
00242   RSSI_ABOVE_TH  = 0x00004000,           /*!< IRQ: RSSI above threshold */
00243   WKUP_TOUT_LDC  = 0x00008000,           /*!< IRQ: Wake-up timeout in LDC mode */
00244   READY  = 0x00010000,                   /*!< IRQ: READY state */
00245   STANDBY_DELAYED  = 0x00020000,         /*!< IRQ: STANDBY state after MCU_CK_CONF_CLOCK_TAIL_X clock cycles */
00246   LOW_BATT_LVL  = 0x00040000,            /*!< IRQ: Battery level below threshold*/
00247   POR  = 0x00080000,                     /*!< IRQ: Power On Reset */
00248   BOR  = 0x00100000,                     /*!< IRQ: Brown out event (both accurate and inaccurate)*/
00249   LOCK  = 0x00200000,                    /*!< IRQ: LOCK state */
00250   PM_COUNT_EXPIRED  = 0x00400000,        /*!< IRQ: only for debug; Power Management startup timer expiration (see reg PM_START_COUNTER, 0xB5) */
00251   XO_COUNT_EXPIRED  = 0x00800000,        /*!< IRQ: only for debug; Crystal oscillator settling time counter expired */
00252   SYNTH_LOCK_TIMEOUT  = 0x01000000,      /*!< IRQ: only for debug; LOCK state timeout */
00253   SYNTH_LOCK_STARTUP  = 0x02000000,      /*!< IRQ: only for debug; see CALIBR_START_COUNTER */
00254   SYNTH_CAL_TIMEOUT  = 0x04000000,       /*!< IRQ: only for debug; SYNTH calibration timeout */
00255   TX_START_TIME  = 0x08000000,           /*!< IRQ: only for debug; TX circuitry startup time; see TX_START_COUNTER */
00256   RX_START_TIME  = 0x10000000,           /*!< IRQ: only for debug; RX circuitry startup time; see TX_START_COUNTER */
00257   RX_TIMEOUT  = 0x20000000,          /*!< IRQ: RX operation timeout */
00258   AES_END  = 0x40000000,                 /*!< IRQ: AES End of operation */
00259   ALL_IRQ  = 0x7FFFFFFF          /*!< All the above mentioned IRQs */
00260 
00261 } IrqList;
00262 
00263 #define IS_SPIRIT_IRQ_LIST(VALUE)   ((VALUE == RX_DATA_READY) || \
00264                                      (VALUE == RX_DATA_DISC)  || \
00265                                      (VALUE == TX_DATA_SENT)  || \
00266                                      (VALUE == MAX_RE_TX_REACH)  || \
00267                                      (VALUE == CRC_ERROR)  || \
00268                                      (VALUE == TX_FIFO_ERROR)  || \
00269                                      (VALUE == RX_FIFO_ERROR)  || \
00270                                      (VALUE == TX_FIFO_ALMOST_FULL)  || \
00271                                      (VALUE == TX_FIFO_ALMOST_EMPTY)  || \
00272                                      (VALUE == RX_FIFO_ALMOST_FULL)  || \
00273                                      (VALUE == RX_FIFO_ALMOST_EMPTY)  || \
00274                                      (VALUE == MAX_BO_CCA_REACH)  || \
00275                                      (VALUE == VALID_PREAMBLE)  || \
00276                                      (VALUE == VALID_SYNC)  || \
00277                                      (VALUE == RSSI_ABOVE_TH)  || \
00278                                      (VALUE == WKUP_TOUT_LDC)  || \
00279                                      (VALUE == READY)  || \
00280                                      (VALUE == STANDBY_DELAYED)  || \
00281                                      (VALUE == LOW_BATT_LVL)  || \
00282                                      (VALUE == POR)  || \
00283                                      (VALUE == BOR)  || \
00284                                      (VALUE == LOCK)  || \
00285                                      (VALUE == PM_COUNT_EXPIRED)  || \
00286                                      (VALUE == XO_COUNT_EXPIRED)  || \
00287                                      (VALUE == SYNTH_LOCK_TIMEOUT)  || \
00288                                      (VALUE == SYNTH_LOCK_STARTUP)  || \
00289                                      (VALUE == SYNTH_CAL_TIMEOUT)  || \
00290                                      (VALUE == TX_START_TIME)  || \
00291                                      (VALUE == RX_START_TIME)  || \
00292                                      (VALUE == RX_TIMEOUT)  || \
00293                                      (VALUE == AES_END)   || \
00294                      (VALUE == ALL_IRQ ))
00295 
00296 
00297 /**
00298  * @}
00299  */
00300 
00301 
00302 /**
00303  * @defgroup Irq_Exported_Constants     IRQ Exported Constants
00304  * @{
00305  */
00306 
00307 
00308 /**
00309  * @}
00310  */
00311 
00312 
00313 /**
00314  * @defgroup Irq_Exported_Macros        IRQ Exported Macros
00315  * @{
00316  */
00317 
00318 
00319 /**
00320  * @}
00321  */
00322 
00323 
00324 /**
00325  * @defgroup Irq_Exported_Functions     IRQ Exported Functions
00326  * @{
00327  */
00328 
00329 void SpiritIrqDeInit(SpiritIrqs* pxIrqInit);
00330 void SpiritIrqInit(SpiritIrqs* pxIrqInit);
00331 void SpiritIrq(IrqList xIrq, SpiritFunctionalState xNewState);
00332 void SpiritIrqGetMask(SpiritIrqs* pxIrqMask);
00333 void SpiritIrqGetStatus(SpiritIrqs* pxIrqStatus);
00334 void SpiritIrqClearStatus(void);
00335 SpiritBool SpiritIrqCheckFlag(IrqList xFlag);
00336 
00337 /**
00338  * @}
00339  */
00340 
00341 /**
00342  * @}
00343  */
00344 
00345 
00346 /**
00347  * @}
00348  */
00349 
00350 
00351 #ifdef __cplusplus
00352 }
00353 #endif
00354 
00355 #endif
00356 
00357 /******************* (C) COPYRIGHT 2015 STMicroelectronics *****END OF FILE****/