1 /*
2 * Copyright (c) 2020 - 2024 Renesas Electronics Corporation and/or its affiliates
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6 
7 /*******************************************************************************************************************//**
8  * @ingroup RENESAS_INPUT_INTERFACES
9  * @defgroup EXTERNAL_IRQ_API External IRQ Interface
10  * @brief Interface for detecting external interrupts.
11  *
12  * @section EXTERNAL_IRQ_API_Summary Summary
13  * The External IRQ Interface is for configuring interrupts to fire when a trigger condition is detected on an
14  * external IRQ pin.
15  *
16  *
17  * @{
18  **********************************************************************************************************************/
19 
20 #ifndef R_EXTERNAL_IRQ_API_H
21 #define R_EXTERNAL_IRQ_API_H
22 
23 /***********************************************************************************************************************
24  * Includes
25  **********************************************************************************************************************/
26 
27 /* Includes board and MCU related header files. */
28 #include "bsp_api.h"
29 
30 /* Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. */
31 FSP_HEADER
32 
33 /**********************************************************************************************************************
34  * Macro definitions
35  *********************************************************************************************************************/
36 
37 /*********************************************************************************************************************
38  * Typedef definitions
39  *********************************************************************************************************************/
40 
41 /** Callback function parameter data */
42 typedef struct st_external_irq_callback_args
43 {
44     /** Placeholder for user data. Set in @ref external_irq_api_t::open function in @ref external_irq_cfg_t. */
45     void const * p_context;
46     uint32_t     channel;              ///< The physical hardware channel that caused the interrupt.
47 } external_irq_callback_args_t;
48 
49 #ifndef BSP_OVERRIDE_EXTERNAL_IRQ_TRIGGER_T
50 
51 /** Condition that will trigger an interrupt when detected. */
52 typedef enum e_external_irq_trigger
53 {
54     EXTERNAL_IRQ_TRIG_FALLING    = 0,  ///< Falling edge trigger
55     EXTERNAL_IRQ_TRIG_RISING     = 1,  ///< Rising edge trigger
56     EXTERNAL_IRQ_TRIG_BOTH_EDGE  = 2,  ///< Both edges trigger
57     EXTERNAL_IRQ_TRIG_LEVEL_LOW  = 3,  ///< Low level trigger
58     EXTERNAL_IRQ_TRIG_LEVEL_HIGH = 4   ///< High level trigger
59 } external_irq_trigger_t;
60 #endif
61 
62 #ifndef BSP_OVERRIDE_EXTERNAL_IRQ_PCLK_DIV_T
63 
64 /** External IRQ input pin digital filtering sample clock divisor settings. The digital filter rejects trigger
65  * conditions that are shorter than 3 periods of the filter clock.
66  */
67 typedef enum e_external_irq_clock_source_div
68 {
69     EXTERNAL_IRQ_CLOCK_SOURCE_DIV_1  = 0, ///< Filter using clock source divided by 1
70     EXTERNAL_IRQ_CLOCK_SOURCE_DIV_8  = 1, ///< Filter using clock source divided by 8
71     EXTERNAL_IRQ_CLOCK_SOURCE_DIV_32 = 2, ///< Filter using clock source divided by 32
72     EXTERNAL_IRQ_CLOCK_SOURCE_DIV_64 = 3, ///< Filter using clock source divided by 64
73 } external_irq_clock_source_div_t;
74 #endif
75 
76 /** User configuration structure, used in open function */
77 typedef struct st_external_irq_cfg
78 {
79     uint8_t                         channel;          ///< Hardware channel used.
80     uint8_t                         ipl;              ///< Interrupt priority
81     IRQn_Type                       irq;              ///< Interrupt number assigned to this instance
82     external_irq_trigger_t          trigger;          ///< Trigger setting.
83     external_irq_clock_source_div_t clock_source_div; ///< Digital filter clock divisor setting.
84     bool filter_enable;                               ///< Digital filter enable/disable setting.
85 
86     /** Callback provided external input trigger occurs. */
87     void (* p_callback)(external_irq_callback_args_t * p_args);
88 
89     /** Placeholder for user data.  Passed to the user callback in @ref external_irq_callback_args_t. */
90     void const * p_context;
91     void const * p_extend;             ///< External IRQ hardware dependent configuration.
92 } external_irq_cfg_t;
93 
94 /** External IRQ control block.  Allocate an instance specific control block to pass into the external IRQ API calls.
95  */
96 typedef void external_irq_ctrl_t;
97 
98 /** External interrupt driver structure. External interrupt functions implemented at the HAL layer will follow this API. */
99 typedef struct st_external_irq_api
100 {
101     /** Initial configuration.
102      *
103      * @param[out]  p_ctrl  Pointer to control block. Must be declared by user. Value set here.
104      * @param[in]   p_cfg   Pointer to configuration structure. All elements of the structure must be set by user.
105      */
106     fsp_err_t (* open)(external_irq_ctrl_t * const p_ctrl, external_irq_cfg_t const * const p_cfg);
107 
108     /** Enable callback when an external trigger condition occurs.
109      *
110      * @param[in]  p_ctrl      Control block set in Open call for this external interrupt.
111      */
112     fsp_err_t (* enable)(external_irq_ctrl_t * const p_ctrl);
113 
114     /** Disable callback when external trigger condition occurs.
115      *
116      * @param[in]  p_ctrl      Control block set in Open call for this external interrupt.
117      */
118     fsp_err_t (* disable)(external_irq_ctrl_t * const p_ctrl);
119 
120     /**
121      * Specify callback function and optional context pointer and working memory pointer.
122      *
123      * @param[in]   p_ctrl                   Pointer to the External IRQ control block.
124      * @param[in]   p_callback               Callback function
125      * @param[in]   p_context                Pointer to send to callback function
126      * @param[in]   p_working_memory         Pointer to volatile memory where callback structure can be allocated.
127      *                                       Callback arguments allocated here are only valid during the callback.
128      */
129     fsp_err_t (* callbackSet)(external_irq_ctrl_t * const p_ctrl, void (* p_callback)(external_irq_callback_args_t *),
130                               void const * const p_context, external_irq_callback_args_t * const p_callback_memory);
131 
132     /** Allow driver to be reconfigured. May reduce power consumption.
133      *
134      * @param[in]  p_ctrl      Control block set in Open call for this external interrupt.
135      */
136     fsp_err_t (* close)(external_irq_ctrl_t * const p_ctrl);
137 } external_irq_api_t;
138 
139 /** This structure encompasses everything that is needed to use an instance of this interface. */
140 typedef struct st_external_irq_instance
141 {
142     external_irq_ctrl_t      * p_ctrl; ///< Pointer to the control structure for this instance
143     external_irq_cfg_t const * p_cfg;  ///< Pointer to the configuration structure for this instance
144     external_irq_api_t const * p_api;  ///< Pointer to the API structure for this instance
145 } external_irq_instance_t;
146 
147 /* Common macro for FSP header files. There is also a corresponding FSP_HEADER macro at the top of this file. */
148 FSP_FOOTER
149 
150 /*******************************************************************************************************************//**
151  * @} (end defgroup EXTERNAL_IRQ_API)
152  **********************************************************************************************************************/
153 
154 #endif
155