1 /*
2  * Copyright (c) 2016-2019, 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       Capture.h
34  *  @brief      Capture Driver
35  *
36  *  @anchor ti_drivers_Capture_Overview
37  *  # Overview
38  *
39  *  The capture driver is used to detect and time edge triggered events on a
40  *  GPIO pin.
41  *
42  *  The capture driver serves as the main interface for a typical RTOS
43  *  application. Its purpose is to redirect the capture APIs to device specific
44  *  implementations which are specified using a pointer to a #Capture_FxnTable.
45  *  The device specific implementations are responsible for creating all the
46  *  RTOS specific primitives to allow for thead-safe operation. The capture
47  *  driver utilizes the general purpose timer hardware.
48  *
49  *  The capture driver internally handles the general purpose timer resource
50  *  allocation. For each capture driver instance, Capture_open() occupies the
51  *  specified timer, and Capture_close() releases the occupied timer resource.
52  *
53  *  <hr>
54  *  @anchor ti_drivers_Capture_Usage
55  *  # Usage
56  *
57  *  This documentation provides a basic @ref ti_drivers_Capture_Synopsis
58  *  "usage summary" and a set of @ref ti_drivers_Capture_Examples "examples"
59  *  in the form of commented code fragments. Detailed descriptions of the
60  *  APIs are provided in subsequent sections.
61  *
62  *  @anchor ti_drivers_Capture_Synopsis
63  *  ## Synopsis
64  *  @anchor ti_drivers_Capture_Synopsis_Code
65  *  @code
66  *  // Import Capture Driver definitions
67  *  #include <ti/drivers/Capture.h>
68  *
69  *  Capture_Handle    handle;
70  *  Capture_Params    params;
71  *
72  *  Capture_Params_init(&params);
73  *  params.mode  = Capture_FALLING_EDGE;
74  *  params.callbackFxn = someCaptureCallbackFunction;
75  *  params.periodUnit = Capture_PERIOD_US;
76  *
77  *  handle = Capture_open(CONFIG_CAPTURE0, &params);
78  *
79  *  if (handle == NULL) {
80  *      //Capture_open() failed
81  *      while(1);
82  *  }
83  *
84  *  status = Capture_start(handle);
85  *
86  *  if (status == Capture_STATUS_ERROR) {
87  *      //Capture_start() failed
88  *      while(1);
89  *  }
90  *
91  *  sleep(10000);
92  *
93  *  Capture_stop(handle);
94  *  @endcode
95  *
96  *  <hr>
97  *  @anchor ti_drivers_Capture_Examples
98  *  # Examples
99  *
100  *  @li @ref ti_drivers_Capture_Examples_open "Opening a Capture instance"
101  *
102  *  @anchor ti_drivers_Capture_Examples_open
103  *  ## Opening a Capture instance
104  *
105  *  @code
106  *  Capture_Handle  handle;
107  *  Capture_Params  params;
108  *
109  *  Capture_Params_init(&params);
110  *  params.mode  = Capture_FALLING_EDGE;
111  *  params.callbackFxn = someCaptureCallbackFunction;
112  *  params.periodUnit = Capture_PERIOD_US;
113  *
114  *  handle = Capture_open(CONFIG_CAPTURE0, &params);
115  *
116  *  if (handle == NULL) {
117  *      //Capture_open() failed
118  *      while(1);
119  *  }
120  *  @endcode
121  *
122  *  <hr>
123  *  @anchor ti_drivers_Capture_Configuration
124  *  # Configuration
125  *
126  *  Refer to the @ref driver_configuration "Driver's Configuration" section
127  *  for driver configuration information.
128  *  <hr>
129  *******************************************************************************
130  */
131 
132 #ifndef ti_drivers_Capture__include
133 #define ti_drivers_Capture__include
134 
135 #include <stdint.h>
136 
137 #ifdef __cplusplus
138 extern "C"
139 {
140 #endif
141 
142 /*!
143  * Common Capture_control command code reservation offset.
144  * Capture driver implementations should offset command codes with
145  * Capture_CMD_RESERVED growing positively.
146  *
147  * Example implementation specific command codes:
148  * @code
149  * #define CaptureXYZ_CMD_COMMAND0      Capture_CMD_RESERVED + 0
150  * #define CaptureXYZ_CMD_COMMAND1      Capture_CMD_RESERVED + 1
151  * @endcode
152  */
153 #define Capture_CMD_RESERVED             (32)
154 
155 /*!
156  * Common Capture_control status code reservation offset.
157  * Capture driver implementations should offset status codes with
158  * Capture_STATUS_RESERVED growing negatively.
159  *
160  * Example implementation specific status codes:
161  * @code
162  * #define CaptureXYZ_STATUS_ERROR0     Capture_STATUS_RESERVED - 0
163  * #define CaptureXYZ_STATUS_ERROR1     Capture_STATUS_RESERVED - 1
164  * @endcode
165  */
166 #define Capture_STATUS_RESERVED         (-32)
167 
168 /*!
169  * @brief   Successful status code.
170  */
171 #define Capture_STATUS_SUCCESS          (0)
172 
173 /*!
174  * @brief   Generic error status code.
175  */
176 #define Capture_STATUS_ERROR            (-1)
177 
178 /*!
179  * @brief   An error status code returned by Capture_control() for undefined
180  * command codes.
181  *
182  * Capture_control() returns Capture_STATUS_UNDEFINEDCMD if the control code is
183  * not recognized by the driver implementation.
184  */
185 #define Capture_STATUS_UNDEFINEDCMD     (-2)
186 
187 /*!
188  *  @brief      A handle that is returned from a Capture_open() call.
189  */
190 typedef struct Capture_Config_ *Capture_Handle;
191 
192 
193 /*!
194  *  @brief Capture mode settings
195  *
196  *  This enum defines the capture modes that may be specified in
197  *  #Capture_Params.
198  *
199  *  Some modes are not available on all devices. Check the device specific
200  *  implementations to see which modes are allowed.
201  */
202 typedef enum {
203     Capture_RISING_EDGE,     /*!< Capture is triggered on rising edges. */
204     Capture_FALLING_EDGE,    /*!< Capture is triggered on falling edges. */
205     Capture_ANY_EDGE,         /*!< Capture is triggered on both rising and
206                                   falling edges. */
207     Capture_RISING_EDGE_FALLING_EDGE,  /*!< Start capture is triggered on rising
208                                             edge and stop capture is triggered
209                                             on falling edge */
210     Capture_FALLING_EDGE_RISING_EDGE,  /*!< Start capture is triggered on
211                                             falling edge and stop capture is
212                                             triggered on rising edge */
213 } Capture_Mode;
214 
215 /*!
216  *  @brief Capture period unit enum
217  *
218  *  This enum defines the units that may be specified for the period
219  *  in #Capture_Params.
220  */
221 typedef enum {
222     Capture_PERIOD_US,       /*!< Period specified in micro seconds. */
223     Capture_PERIOD_HZ,       /*!< Period specified in hertz; interrupts per
224                                   second. */
225     Capture_PERIOD_COUNTS,    /*!< Period specified in timer ticks. Varies
226                                   by board. */
227     Capture_PERIOD_NS,       /*!< Period specified in nano seconds. */
228 } Capture_PeriodUnits;
229 
230 
231 /*!
232  *  @brief  Capture callback function
233  *
234  *  User definable callback function prototype. The capture driver will call
235  *  the defined function and pass in the capture driver's handle and the
236  *  pointer to the user-specified the argument.
237  *
238  *  @param[in]  handle         Capture_Handle
239  *
240  *  @param[in]  interval       Interval of two triggering edges in
241  *                             #Capture_PeriodUnits
242  *  @param[in]  status         Status of Capture interrupt
243  */
244 typedef void (*Capture_CallBackFxn)(Capture_Handle handle, uint32_t interval,
245                                     int_fast16_t status);
246 
247 /*!
248  *  @brief Capture Parameters
249  *
250  *  Capture parameters are used by the Capture_open() call. Default values for
251  *  these parameters are set using Capture_Params_init().
252  *
253  */
254 typedef struct {
255     /*! Mode to be used by the timer driver. */
256     Capture_Mode           mode;
257 
258     /*! Callback function called when a trigger event occurs. */
259     Capture_CallBackFxn    callbackFxn;
260 
261     /*! Units used to specify the interval. */
262     Capture_PeriodUnits    periodUnit;
263 } Capture_Params;
264 
265 /*!
266  *  @brief      A function pointer to a driver specific implementation of
267  *              Capture_close().
268  */
269 typedef void (*Capture_CloseFxn)(Capture_Handle handle);
270 
271 /*!
272  *  @brief      A function pointer to a driver specific implementation of
273  *              Capture_control().
274  */
275 typedef int_fast16_t (*Capture_ControlFxn)(Capture_Handle handle,
276     uint_fast16_t cmd, void *arg);
277 
278 /*!
279  *  @brief      A function pointer to a driver specific implementation of
280  *              Capture_init().
281  */
282 typedef void (*Capture_InitFxn)(Capture_Handle handle);
283 
284 /*!
285  *  @brief      A function pointer to a driver specific implementation of
286  *              Capture_open().
287  */
288 typedef Capture_Handle (*Capture_OpenFxn)(Capture_Handle handle,
289     Capture_Params *params);
290 
291 /*!
292  *  @brief      A function pointer to a driver specific implementation of
293  *              Capture_start().
294  */
295 typedef int32_t (*Capture_StartFxn)(Capture_Handle handle);
296 
297 /*!
298  *  @brief      A function pointer to a driver specific implementation of
299  *              Capture_stop().
300  */
301 typedef void (*Capture_StopFxn)(Capture_Handle handle);
302 
303 /*!
304  *  @brief      The definition of a capture function table that contains the
305  *              required set of functions to control a specific capture driver
306  *              implementation.
307  */
308 typedef struct {
309     /*! Function to close the specified peripheral. */
310     Capture_CloseFxn closeFxn;
311 
312     /*! Function to implementation specific control function. */
313     Capture_ControlFxn controlFxn;
314 
315     /*! Function to initialize the given data object. */
316     Capture_InitFxn initFxn;
317 
318     /*! Function to open the specified peripheral. */
319     Capture_OpenFxn openFxn;
320 
321     /*! Function to start the specified peripheral. */
322     Capture_StartFxn startFxn;
323 
324     /*! Function to stop the specified peripheral. */
325     Capture_StopFxn stopFxn;
326 } Capture_FxnTable;
327 
328 /*!
329  *  @brief  Capture Global configuration
330  *
331  *  The Capture_Config structure contains a set of pointers used to
332  *  characterize the capture driver implementation.
333  *
334  *  This structure needs to be defined before calling Capture_init() and it
335  *  must not be changed thereafter.
336  *
337  *  @sa     Capture_init()
338  */
339 typedef struct Capture_Config_ {
340     /*! Pointer to a table of driver-specific implementations of capture
341         APIs. */
342     Capture_FxnTable const *fxnTablePtr;
343 
344     /*! Pointer to a driver specific data object. */
345     void                   *object;
346 
347     /*! Pointer to a driver specific hardware attributes structure. */
348     void             const *hwAttrs;
349 } Capture_Config;
350 
351 /*!
352  *  @brief  Function to close a capture driver instance. The corresponding
353  *          timer peripheral to Capture_handle becomes an available resource.
354  *
355  *  @pre    Capture_open() has been called.
356  *
357  *  @param[in]  handle  A Capture_Handle returned from Capture_open().
358  *
359  *  @sa     Capture_open()
360  */
361 extern void Capture_close(Capture_Handle handle);
362 
363 /*!
364  *  @brief  Function performs implementation specific features on a given
365  *          Capture_Handle.
366  *
367  *  @pre    Capture_open() has been called.
368  *
369  *  @param[in]  handle      A Capture_Handle returned from Capture_open().
370  *
371  *  @param[in]  cmd         A command value defined by the driver specific
372  *                      implementation.
373  *
374  *  @param[in]  arg         A pointer to an optional R/W (read/write) argument that
375  *                      is accompanied with cmd.
376  *
377  *  @retval #Capture_STATUS_SUCCESS  The control call was successful.
378  *  @retval #Capture_STATUS_ERROR    The control call failed.
379  *
380  *  @sa     Capture_open()
381  */
382 extern int_fast16_t Capture_control(Capture_Handle handle, uint_fast16_t cmd,
383     void *arg);
384 
385 /*!
386  *  @brief  Function to initialize the capture driver. This function will go
387  *          through all available hardware resources and mark them as
388  *          "available".
389  *
390  *  @pre    The Capture_config structure must exist and be persistent before
391  *          this function can be called. This function must also be called
392  *          before any other capture driver APIs.
393  *
394  *  @sa     Capture_open()
395  */
396 extern void Capture_init(void);
397 
398 /*!
399  *  @brief  Function to open a given capture instance specified by the
400  *          index argument. The Capture_Params specifies which mode the capture
401  *          instance will operate. This function takes care of capture resource
402  *          allocation. If the particular timer hardware is available to use,
403  *          the capture driver acquires it and returns a Capture_Handle.
404  *
405  *  @pre    Capture_init() has been called.
406  *
407  *  @param[in]  index         Logical instance number for the capture indexed into
408  *                        the Capture_config table.
409  *
410  *  @param[in]  params        Pointer to a parameter block. Cannot be NULL.
411  *
412  *  @return A #Capture_Handle on success, or NULL if the timer peripheral is
413  *          already in use.
414  *
415  *  @sa     Capture_init()
416  *  @sa     Capture_close()
417  */
418 extern Capture_Handle Capture_open(uint_least8_t index, Capture_Params *params);
419 
420 /*!
421  *  @brief  Function to initialize the Capture_Params struct to its defaults.
422  *
423  *  @param[in]  params      An pointer to Capture_Params structure for
424  *                      initialization.
425  *
426  *  Defaults values are:
427  *      callbackFxn = NULL
428  *      mode = #Capture_RISING_EDGE
429  *      periodUnit = #Capture_PERIOD_COUNTS
430  */
431 extern void Capture_Params_init(Capture_Params *params);
432 
433 /*!
434  *  @brief  Function to start the capture instance.
435  *
436  *  @pre    Capture_open() has been called.
437  *
438  *  @param[in]  handle  A Capture_Handle returned from Capture_open().
439  *
440  *  @retval #Capture_STATUS_SUCCESS  The start call was successful.
441  *  @retval #Capture_STATUS_ERROR    The start call failed.
442  *
443  *  @sa     Capture_stop().
444  *
445  */
446 extern int32_t Capture_start(Capture_Handle handle);
447 
448 /*!
449  *  @brief  Function to stop a capture instance. If the capture instance is
450  *          already stopped, this function has no effect.
451  *
452  *  @pre    Capture_open() has been called.
453  *
454  *  @param[in]  handle  A Capture_Handle returned from Capture_open().
455  *
456  *  @sa     Capture_start()
457  */
458 extern void Capture_stop(Capture_Handle handle);
459 
460 #ifdef __cplusplus
461 }
462 #endif
463 
464 #endif /* ti_drivers_Capture__include */
465