1 /*********************************************************************************************************************** 2 * Copyright [2015-2017] Renesas Electronics Corporation and/or its licensors. All Rights Reserved. 3 * 4 * This file is part of Renesas SynergyTM Software Package (SSP) 5 * 6 * The contents of this file (the "contents") are proprietary and confidential to Renesas Electronics Corporation 7 * and/or its licensors ("Renesas") and subject to statutory and contractual protections. 8 * 9 * This file is subject to a Renesas SSP license agreement. Unless otherwise agreed in an SSP license agreement with 10 * Renesas: 1) you may not use, copy, modify, distribute, display, or perform the contents; 2) you may not use any name 11 * or mark of Renesas for advertising or publicity purposes or in connection with your use of the contents; 3) RENESAS 12 * MAKES NO WARRANTY OR REPRESENTATIONS ABOUT THE SUITABILITY OF THE CONTENTS FOR ANY PURPOSE; THE CONTENTS ARE PROVIDED 13 * "AS IS" WITHOUT ANY EXPRESS OR IMPLIED WARRANTY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 14 * PARTICULAR PURPOSE, AND NON-INFRINGEMENT; AND 4) RENESAS SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, OR 15 * CONSEQUENTIAL DAMAGES, INCLUDING DAMAGES RESULTING FROM LOSS OF USE, DATA, OR PROJECTS, WHETHER IN AN ACTION OF 16 * CONTRACT OR TORT, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE CONTENTS. Third-party contents 17 * included in this file may be subject to different terms. 18 **********************************************************************************************************************/ 19 20 /********************************************************************************************************************** 21 * File Name : r_input_capture_api.h 22 * Description : Input Capture API. Allows sampling of input signals for pulse width. 23 **********************************************************************************************************************/ 24 25 #ifndef R_INPUT_CAPTURE_API_H 26 #define R_INPUT_CAPTURE_API_H 27 28 /*******************************************************************************************************************//** 29 * @ingroup Interface_Library 30 * @defgroup INPUT_CAPTURE_API Input Capture Interface 31 * 32 * @brief Interface for sampling input signals for pulse width. 33 * 34 * @section INPUT_CAPTURE_API_SUMMARY Summary 35 * The input capture interface provides for sampling of input signals to determine the width of a pulse (from one edge 36 * to the opposite edge). An interrupt can be triggered after each measurement is captured. 37 * 38 * Implemented by: 39 * - @ref GPT_INPUT_CAPTURE 40 * - @ref AGT_INPUT_CAPTURE 41 * 42 * See also: @ref TIMER_API 43 * 44 * Related SSP architecture topics: 45 * - @ref ssp-interfaces 46 * - @ref ssp-predefined-layers 47 * - @ref using-ssp-modules 48 * 49 * @{ 50 **********************************************************************************************************************/ 51 52 /*********************************************************************************************************************** 53 * Includes 54 **********************************************************************************************************************/ 55 /* Includes board and MCU related header files. */ 56 #include "bsp_api.h" 57 58 /* Common macro for SSP header files. There is also a corresponding SSP_FOOTER macro at the end of this file. */ 59 SSP_HEADER 60 61 /********************************************************************************************************************** 62 * Macro definitions 63 **********************************************************************************************************************/ 64 #define INPUT_CAPTURE_API_VERSION_MAJOR (1U) 65 #define INPUT_CAPTURE_API_VERSION_MINOR (7U) 66 67 /** Mapping of deprecated info_capture_info_t. */ 68 #define info_capture_info_t input_capture_info_t 69 70 /********************************************************************************************************************** 71 * Typedef definitions 72 **********************************************************************************************************************/ 73 /** Input capture operational modes */ 74 typedef enum e_input_capture_mode 75 { 76 INPUT_CAPTURE_MODE_PULSE_WIDTH, ///< Measure a signal pulse width. 77 INPUT_CAPTURE_MODE_PERIOD, ///< Measure a signal Cycle period. 78 INPUT_CAPTURE_MODE_PULSE_COUNT, ///< Measure a signal event count. 79 } input_capture_mode_t; 80 81 /** Input capture signal edge trigger */ 82 typedef enum e_input_capture_signal_edge 83 { 84 INPUT_CAPTURE_SIGNAL_EDGE_RISING, ///< The capture begins at the rising edge. 85 INPUT_CAPTURE_SIGNAL_EDGE_FALLING, ///< The capture begins at the falling edge. 86 } input_capture_signal_edge_t; 87 88 /** Input capture signal level, primarily used for the enable signal */ 89 typedef enum e_input_capture_signal_level 90 { 91 INPUT_CAPTURE_SIGNAL_LEVEL_NONE, ///< Use this if signal_level is not applicable to a particular measurement. 92 INPUT_CAPTURE_SIGNAL_LEVEL_LOW, ///< The capture is enabled at the low level. 93 INPUT_CAPTURE_SIGNAL_LEVEL_HIGH, ///< The capture is enabled at the high level. 94 } input_capture_signal_level_t; 95 96 /** Specifies either a one-time or continuous measurements */ 97 typedef enum e_input_capture_repetition 98 { 99 INPUT_CAPTURE_REPETITION_PERIODIC, ///< Capture continuous measurements, until explicitly stopped or disabled. 100 INPUT_CAPTURE_REPETITION_ONE_SHOT, ///< Capture a single measurement, then interrupts are disabled. 101 } input_capture_repetition_t; 102 103 /** Events that can trigger a callback function */ 104 typedef enum e_input_capture_event 105 { 106 INPUT_CAPTURE_EVENT_MEASUREMENT, ///< A capture measurement has been captured. 107 INPUT_CAPTURE_EVENT_OVERFLOW, ///< A capture measurement overflowed the counter. 108 } input_capture_event_t; 109 110 /** Input capture status. */ 111 typedef enum e_input_capture_status 112 { 113 INPUT_CAPTURE_STATUS_IDLE, ///< The input capture timer is idle. 114 INPUT_CAPTURE_STATUS_CAPTURING, ///< A capture measurement is in progress. 115 } input_capture_status_t; 116 117 /** Input capture timer variant types. */ 118 typedef enum e_input_capture_variant 119 { 120 INPUT_CAPTURE_VARIANT_32_BIT, ///< 32-bit timer 121 INPUT_CAPTURE_VARIANT_16_BIT ///< 16-bit timer 122 } input_capture_variant_t; 123 124 /** Callback function parameter data */ 125 typedef struct st_input_capture_callback_args 126 { 127 uint8_t channel; ///< The channel being used. 128 input_capture_event_t event; ///< The event that caused the interrupt and callback. 129 uint32_t counter; ///< The value of the timer captured at the time of interrupt. 130 uint32_t overflows; ///< The number of counter overflows that occurred during this measurement 131 void const * p_context; ///< Placeholder for user data, set in input_capture_cfg_t::p_context. 132 } input_capture_callback_args_t; 133 134 /** Capture data */ 135 typedef struct st_input_capture_capture 136 { 137 uint32_t counter; ///< The value of the timer captured at the time of interrupt. 138 uint32_t overflows; ///< The number of counter overflows that occurred during this measurement 139 } input_capture_capture_t; 140 141 /** Driver information */ 142 typedef struct st_input_capture_info 143 { 144 input_capture_status_t status; ///< Whether or not a capture is in progress 145 input_capture_variant_t variant; ///< Whether timer is 16 or 32 bits. 146 } input_capture_info_t; 147 148 /** Input capture control block. Allocate an instance specific control block to pass into the input capture API calls. 149 * @par Implemented as 150 * - gpt_input_capture_instance_ctrl_t 151 * - agt_input_capture_instance_ctrl_t 152 */ 153 typedef void input_capture_ctrl_t; 154 155 /** User configuration structure, passed to input_capture_api_t::open function */ 156 typedef struct st_input_capture_cfg 157 { 158 uint8_t channel; ///< The channel in use. 159 uint8_t capture_irq_ipl; ///< Capture interrupt priority 160 uint8_t overflow_irq_ipl; ///< Overflow interrupt priority 161 input_capture_mode_t mode; ///< The mode of measurement to be performed. 162 input_capture_signal_edge_t edge; ///< The triggering edge to start a measurement (rise or fall). 163 input_capture_repetition_t repetition; ///< One-shot or periodic measurement. 164 bool autostart; ///< Specifies whether interrupts are enabled or not after open. 165 166 /** REQUIRED. Pointer to peripheral-specific extension parameters. See gpt_input_capture_extend_t for GPT. */ 167 void const * p_extend; 168 169 /** Pointer to user's callback function, or NULL if no interrupt desired. */ 170 void (*p_callback) (input_capture_callback_args_t * p_args); 171 void const * p_context; ///< Pointer to user's context data, to be passed to the callback 172 // function. 173 } input_capture_cfg_t; 174 175 /** Input capture API structure. Functions implemented at the HAL layer will implement this API. */ 176 typedef struct st_input_capture_api 177 { 178 /** Initial configuration. 179 * @par Implemented as 180 * - R_GPT_InputCaptureOpen() 181 * - R_AGT_InputCaptureOpen() 182 * 183 * @note To reconfigure after calling this function, call input_capture_api_t::close first. 184 * @param[in] p_ctrl Pointer to control block: memory allocated by caller, contents filled in by open. 185 * @param[in] p_cfg Pointer to configuration structure. All elements of this structure must be set by user. 186 */ 187 ssp_err_t (* open)(input_capture_ctrl_t * const p_ctrl, 188 input_capture_cfg_t const * const p_cfg); 189 190 /** Disables input capture measurement. 191 * @par Implemented as 192 * - R_GPT_InputCaptureDisable() 193 * - R_AGT_InputCaptureDisable() 194 * 195 * @param[in] p_ctrl Pointer to control block initialized by input_capture_api_t::open call. 196 */ 197 ssp_err_t (* disable)(input_capture_ctrl_t const * const p_ctrl); 198 199 /** Enables input capture measurement. 200 * @par Implemented as 201 * - R_GPT_InputCaptureEnable() 202 * - R_AGT_InputCaptureEnable() 203 * 204 * @param[in] p_ctrl Pointer to control block initialized by input_capture_api_t::open call. 205 * @note Interrupts may already be enabled if specified by input_capture_cfg_t::irq_enable. 206 */ 207 ssp_err_t (* enable)(input_capture_ctrl_t const * const p_ctrl); 208 209 /** Gets the status (running or not) of the measurement counter. 210 * @par Implemented as 211 * - R_GPT_InputCaptureInfoGet() 212 * - R_AGT_InputCaptureInfoGet() 213 * 214 * @param[in] p_ctrl Pointer to control block initialized by input_capture_api_t::open call. 215 * @param[out] p_info Pointer to returned status. Result will be one of input_capture_status_t. 216 */ 217 ssp_err_t (* infoGet)(input_capture_ctrl_t const * const p_ctrl, 218 input_capture_info_t * const p_info); 219 220 /** Gets the last captured timer/counter value 221 * @par Implemented as 222 * - R_GPT_InputCaptureLastCaptureGet() 223 * - R_AGT_InputCaptureLastCaptureGet() 224 * 225 * @param[in] p_ctrl Pointer to control block initialized by input_capture_api_t::open call. 226 * @param[out] p_counter Pointer to location to store last captured counter value. 227 */ 228 ssp_err_t (* lastCaptureGet)(input_capture_ctrl_t const * const p_ctrl, 229 input_capture_capture_t * const p_counter); 230 231 /** Close the input capture operation. Allows driver to be reconfigured, and may reduce power consumption. 232 * @par Implemented as 233 * - R_GPT_InputCaptureClose() 234 * - R_AGT_InputCaptureClose() 235 * 236 * @param[in] p_ctrl Pointer to control block initialized by input_capture_api_t::open call. 237 */ 238 ssp_err_t (* close)(input_capture_ctrl_t * const p_ctrl); 239 240 /** Gets the version of this API and stores it in structure pointed to by p_version. 241 * @par Implemented as 242 * - R_GPT_InputCaptureVersionGet() 243 * - R_AGT_InputCaptureVersionGet() 244 * 245 * @param[out] p_version Code and API version used. 246 */ 247 ssp_err_t (* versionGet)(ssp_version_t * const p_version); 248 } input_capture_api_t; 249 250 /** This structure encompasses everything that is needed to use an instance of this interface. */ 251 typedef struct st_input_capture_instance 252 { 253 input_capture_ctrl_t * p_ctrl; ///< Pointer to the control structure for this instance 254 input_capture_cfg_t const * p_cfg; ///< Pointer to the configuration structure for this instance 255 input_capture_api_t const * p_api; ///< Pointer to the API structure for this instance 256 } input_capture_instance_t; 257 258 /*******************************************************************************************************************//** 259 * @} (end defgroup INPUT_CAPTURE_API) 260 **********************************************************************************************************************/ 261 262 /* Common macro for SSP header files. There is also a corresponding SSP_HEADER macro at the top of this file. */ 263 SSP_FOOTER 264 265 #endif /* R_INPUT_CAPTURE_API_H */ 266