git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_M4_SimpleLink_CC3220SF_CCS/ti/drivers/dpl/HwiP.h

   1 /*
   2  * Copyright (c) 2015-2016, Texas Instruments Incorporated
   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
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32 /** ============================================================================
  33  *  @file       HwiP.h
  34  *
  35  *  @brief      Hardware Interrupt module for the RTOS Porting Interface
  36  *
  37  *  The ::HwiP_disable/::HwiP_restore APIs can be called recursively. The order
  38  *  of the HwiP_restore calls, must be in reversed order. For example:
  39  *  @code
  40  *  uintptr_t key1, key2;
  41  *  key1 = HwiP_disable();
  42  *  key2 = HwiP_disable();
  43  *  HwiP_restore(key2);
  44  *  HwiP_restore(key1);
  45  *  @endcode
  46  *
  47  *  ============================================================================
  48  */
  49
  50 #ifndef ti_dpl_HwiP__include
  51 #define ti_dpl_HwiP__include
  52
  53 #ifdef __cplusplus
  54 extern "C" {
  55 #endif
  56
  57 #include <stdint.h>
  58 #include <stdbool.h>
  59 #include <stddef.h>
  60
  61 /*!
  62  *  @brief    Opaque client reference to an instance of a HwiP
  63  *
  64  *  A HwiP_Handle returned from the ::HwiP_create represents that instance.
  65  */
  66 typedef  void *HwiP_Handle;
  67
  68 /*!
  69  *  @brief    Status codes for HwiP APIs
  70  */
  71 typedef enum HwiP_Status {
  72     HwiP_OK = 0,
  73     HwiP_FAILURE = -1
  74 } HwiP_Status;
  75
  76 /*!
  77  *  @brief  Prototype for the entry function for a hardware interrupt
  78  */
  79 typedef void (*HwiP_Fxn)(uintptr_t arg);
  80
  81 /*!
  82  *  @brief    Basic HwiP Parameters
  83  *
  84  *  Structure that contains the parameters passed into ::HwiP_create
  85  *  when creating a HwiP instance. The ::HwiP_Params_init function should
  86  *  be used to initialize the fields to default values before the application sets
  87  *  the fields manually. The HwiP default parameters are noted in
  88  *  HwiP_Params_init.
  89  */
  90 typedef struct HwiP_Params {
  91     char      *name;      /*!< Name of the clock instance. Memory must
  92                                persist for the life of the clock instance.
  93                                This can be used for debugging purposes, or
  94                                set to NULL if not needed. */
  95     uintptr_t  arg;       /*!< Argument passed into the Hwi function. */
  96     uint32_t   priority;  /*!< Device specific priority. */
  97 } HwiP_Params;
  98
  99 /*!
 100  *  @brief  Function to clear a single interrupt
 101  *
 102  *  @param  interruptNum interrupt number to clear
 103  */
 104 extern void HwiP_clearInterrupt(int interruptNum);
 105
 106 /*!
 107  *  @brief  Function to create an interrupt on CortexM devices
 108  *
 109  *  @param  interruptNum Interrupt Vector Id
 110  *
 111  *  @param  hwiFxn entry function of the hardware interrupt
 112  *
 113  *  @param  params    Pointer to the instance configuration parameters. NULL
 114  *                    denotes to use the default parameters. The HwiP default
 115  *                    parameters are noted in ::HwiP_Params_init.
 116  *
 117  *  @return A HwiP_Handle on success or a NULL on an error
 118  */
 119 extern HwiP_Handle HwiP_create(int interruptNum, HwiP_Fxn hwiFxn,
 120                                HwiP_Params *params);
 121
 122 /*!
 123  *  @brief  Function to delete an interrupt on CortexM devices
 124  *
 125  *  @param  handle returned from the HwiP_create call
 126  *
 127  *  @return
 128  */
 129 extern HwiP_Status HwiP_delete(HwiP_Handle handle);
 130
 131 /*!
 132  *  @brief  Function to disable interrupts to enter a critical region
 133  *
 134  *  This function can be called multiple times, but must unwound in the reverse
 135  *  order. For example
 136  *  @code
 137  *  uintptr_t key1, key2;
 138  *  key1 = HwiP_disable();
 139  *  key2 = HwiP_disable();
 140  *  HwiP_restore(key2);
 141  *  HwiP_restore(key1);
 142  *  @endcode
 143  *
 144  *  @return A key that must be passed to HwiP_restore to re-enable interrupts.
 145  */
 146 extern uintptr_t HwiP_disable(void);
 147
 148 /*!
 149  *  @brief  Function to disable a single interrupt
 150  *
 151  *  @param  interruptNum interrupt number to disable
 152  */
 153 extern void HwiP_disableInterrupt(int interruptNum);
 154
 155 /*!
 156  *  @brief  Function to enable a single interrupt
 157  *
 158  *  @param  interruptNum interrupt number to enable
 159  */
 160 extern void HwiP_enableInterrupt(int interruptNum);
 161
 162 /*!
 163  *  @brief  Function  to return a status based on whether it is in an interrupt
 164  *      context.
 165  *
 166  *  @return A status: indicating whether the function was called in an
 167  *      ISR (true) or at thread level (false).
 168  */
 169 extern bool HwiP_inISR(void);
 170
 171 /*!
 172  *  @brief  Initialize params structure to default values.
 173  *
 174  *  The default parameters are:
 175  *   - name: NULL
 176  *   - arg: 0
 177  *   - priority: ~0
 178  *
 179  *  @param params  Pointer to the instance configuration parameters.
 180  */
 181 extern void HwiP_Params_init(HwiP_Params *params);
 182
 183 /*!
 184  *  @brief  Function to restore interrupts to exit a critical region
 185  *
 186  *  @param  key return from HwiP_disable
 187  */
 188 extern void HwiP_restore(uintptr_t key);
 189
 190 #ifdef __cplusplus
 191 }
 192 #endif
 193
 194 #endif /* ti_dpl_HwiP__include */