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