Capture.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016-2017, 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 interface
35  *
36  * The capture header file should be included in an application as follows:
37  * @code
38  * #include <ti/drivers/Capture.h>
39  * @endcode
40  *
41  * # Overview #
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  * # Usage#
54  * The capture driver is used to detect and time edge triggered events on a
55  * GPIO pin. The following example code opens a capture instance in falling
56  * edge mode. The interval returned in the callback function is in
57  * microseconds.
58  *
59  * @code
60  * Capture_Handle handle;
61  * Capture_Params params;
62  *
63  * Capture_Params_init(&params);
64  * params.mode = Capture_FALLING_EDGE;
65  * params.callbackFxn = someCaptureCallbackFunction;
66  * params.periodUnit = Capture_PERIOD_US;
67  *
68  * handle = Capture_open(someCapture_configIndexValue, &params);
69  *
70  * if (handle == NULL) {
71  * //Capture_open() failed
72  * while(1);
73  * }
74  *
75  * status = Capture_start(handle);
76  *
77  * if (status == Capture_STATUS_ERROR) {
78  * //Capture_start() failed
79  * while(1);
80  * }
81  *
82  * sleep(10000);
83  *
84  * Capture_stop(handle);
85  * @endcode
86 
87  * ### Capture Driver Configuration #
88  *
89  * In order to use the capture APIs, the application is required to provide
90  * device specific capture configuration in the Board.c file. The capture
91  * driver interface defines a configuration data structure:
92  *
93  * @code
94  * typedef struct Capture_Config_ {
95  * Capture_FxnTable const *fxnTablePtr;
96  * void *object;
97  * void const *hwAttrs;
98  * } Capture_Config;
99  * @endcode
100  *
101  * The application must declare an array of Capture_Config elements, named
102  * Capture_config[]. Each element of Capture_config[] is populated with
103  * pointers to a device specific capture driver implementation's function
104  * table, driver object, and hardware attributes. The hardware attributes
105  * define properties such as the timer peripheral's base address, interrupt
106  * number and interrupt priority. Each element in Capture_config[] corresponds
107  * to a capture instance, and none of the elements should have NULL pointers.
108  * There is no correlation between the index and the peripheral designation.
109  *
110  * You will need to check the device specific capture driver implementation's
111  * header file for example configuration.
112  *
113  * ### Initializing the Capture Driver #
114  *
115  * Capture_init() must be called before any other capture APIs. This function
116  * calls the device implementation's capture initialization function, for each
117  * element of Capture_config[].
118  *
119  * ### Modes of Operation #
120  *
121  * The capture driver supports four modes of operation which may be specified
122  * in the Capture_Params.
123  *
124  * #Capture_RISING_EDGE will capture rising edge triggers. After
125  * Capture_start() is called, the callback function specified in
126  * Capture_Params will be called after each rising edge is detected on the
127  * GPIO pin. This behavior will continue until Capture_stop() is called.
128  *
129  * #Capture_FALLING_EDGE will capture falling edge triggers. After
130  * Capture_start() is called, the callback function specified in
131  * Capture_Params will be called after each falling edge is detected on the
132  * GPIO pin. This behavior will continue until Capture_stop() is called.
133  *
134  * #Capture_ANY_EDGE will capture both rising and falling edge triggers. After
135  * Capture_start() is called, the callback function specified in
136  * Capture_Params will be called after each rising or falling edge is detected
137  * on the GPIO pin. This behavior will continue until Capture_stop() is
138  * called.
139  *
140  * # Implementation #
141  *
142  * The capture driver interface module is joined (at link time) to an
143  * array of Capture_Config data structures named *Capture_config*.
144  * Capture_config is implemented in the application with each entry being an
145  * instance of a capture peripheral. Each entry in *Capture_config* contains a:
146  * - (Capture_FxnTable *) to a set of functions that implement a capture
147  * peripheral
148  * - (void *) data object that is associated with the Capture_FxnTable
149  * - (void *) hardware attributes that are associated with the Capture_FxnTable
150  *
151  * The capture APIs are redirected to the device specific implementations
152  * using the Capture_FxnTable pointer of the Capture_config entry.
153  * In order to use device specific functions of the capture driver directly,
154  * link in the correct driver library for your device and include the
155  * device specific capture driver header file (which in turn includes
156  * Capture.h). For example, for the MSP432 family of devices, you would
157  * include the following header file:
158  *
159  * @code
160  * #include <ti/drivers/capture/CaptureMSP432.h>
161  * @endcode
162  *
163  *******************************************************************************
164  */
165 
166 #ifndef ti_drivers_Capture__include
167 #define ti_drivers_Capture__include
168 
169 #ifdef __cplusplus
170 extern "C"
171 {
172 #endif
173 
174 #include <stdint.h>
175 
187 #define Capture_CMD_RESERVED (32)
188 
200 #define Capture_STATUS_RESERVED (-32)
201 
205 #define Capture_STATUS_SUCCESS (0)
206 
210 #define Capture_STATUS_ERROR (-1)
211 
219 #define Capture_STATUS_UNDEFINEDCMD (-2)
220 
225 
226 
233 typedef enum Capture_Mode_ {
238 } Capture_Mode;
239 
246 typedef enum Capture_PeriodUnits_ {
253 
254 
267 typedef void (*Capture_CallBackFxn)(Capture_Handle handle, uint32_t interval);
268 
276 typedef struct Capture_Params_ {
278  Capture_Mode mode;
279 
282 
284  Capture_PeriodUnits periodUnit;
286 
291 typedef void (*Capture_CloseFxn)(Capture_Handle handle);
292 
297 typedef int_fast16_t (*Capture_ControlFxn)(Capture_Handle handle,
298  uint_fast16_t cmd, void *arg);
299 
304 typedef void (*Capture_InitFxn)(Capture_Handle handle);
305 
310 typedef Capture_Handle (*Capture_OpenFxn)(Capture_Handle handle,
311  Capture_Params *params);
312 
317 typedef int32_t (*Capture_StartFxn)(Capture_Handle handle);
318 
323 typedef void (*Capture_StopFxn)(Capture_Handle handle);
324 
330 typedef struct Capture_FxnTable_ {
333 
336 
339 
342 
345 
349 
361 typedef struct Capture_Config_ {
365 
367  void *object;
368 
370  void const *hwAttrs;
372 
383 extern void Capture_close(Capture_Handle handle);
384 
404 extern int_fast16_t Capture_control(Capture_Handle handle, uint_fast16_t cmd,
405  void *arg);
406 
418 extern void Capture_init(void);
419 
440 extern Capture_Handle Capture_open(uint_least8_t index, Capture_Params *params);
441 
453 extern void Capture_Params_init(Capture_Params *params);
454 
467 extern int32_t Capture_start(Capture_Handle handle);
468 
479 extern void Capture_stop(Capture_Handle handle);
480 
481 /* The following are included for backwards compatibility. These should not be
482  * used by the application.
483  */
484 #define CAPTURE_CMD_RESERVED Capture_CMD_RESERVED
485 #define CAPTURE_STATUS_RESERVED Capture_STATUS_RESERVED
486 #define CAPTURE_STATUS_SUCCESS Capture_STATUS_SUCCESS
487 #define CAPTURE_STATUS_ERROR Capture_STATUS_ERROR
488 #define CAPTURE_STATUS_UNDEFINEDCMD Capture_STATUS_UNDEFINEDCMD
489 #define CAPTURE_MODE_RISING_RISING Capture_RISING_EDGE
490 #define CAPTURE_MODE_FALLING_FALLING Capture_FALLING_EDGE
491 #define CAPTURE_MODE_ANY_EDGE Capture_ANY_EDGE
492 #define CAPTURE_PERIOD_US Capture_PERIOD_US
493 #define CAPTURE_PERIOD_HZ Capture_PERIOD_HZ
494 #define CAPTURE_PERIOD_COUNTS Capture_PERIOD_COUNTS
495 #define Capture_Period_Unit Capture_PeriodUnits
496 
497 #ifdef __cplusplus
498 }
499 #endif
500 
501 #endif /* ti_drivers_Capture__include */
struct Capture_FxnTable_ Capture_FxnTable
The definition of a capture function table that contains the required set of functions to control a s...
void Capture_stop(Capture_Handle handle)
Function to stop a capture instance. If the capture instance is already stopped, this function has no...
Capture_OpenFxn openFxn
Definition: Capture.h:341
Capture Global configuration.
Definition: Capture.h:361
Definition: Capture.h:236
Capture_Handle(* Capture_OpenFxn)(Capture_Handle handle, Capture_Params *params)
A function pointer to a driver specific implementation of Capture_open().
Definition: Capture.h:310
void(* Capture_CloseFxn)(Capture_Handle handle)
A function pointer to a driver specific implementation of Capture_close().
Definition: Capture.h:291
Capture Parameters.
Definition: Capture.h:276
Capture_Mode_
Capture mode settings.
Definition: Capture.h:233
Capture_Handle Capture_open(uint_least8_t index, Capture_Params *params)
Function to open a given capture instance specified by the index argument. The Capture_Params specifi...
enum Capture_Mode_ Capture_Mode
Capture mode settings.
enum Capture_PeriodUnits_ Capture_PeriodUnits
Capture period unit enum.
struct Capture_Config_ Capture_Config
Capture Global configuration.
int32_t Capture_start(Capture_Handle handle)
Function to start the capture instance.
void Capture_init(void)
Function to initialize the capture driver. This function will go through all available hardware resou...
void * object
Definition: Capture.h:367
Capture_CallBackFxn callbackFxn
Definition: Capture.h:281
Capture_StartFxn startFxn
Definition: Capture.h:344
Definition: Capture.h:234
void Capture_Params_init(Capture_Params *params)
Function to initialize the Capture_Params struct to its defaults.
Capture_PeriodUnits periodUnit
Definition: Capture.h:284
struct Capture_Params_ Capture_Params
Capture Parameters.
Capture_CloseFxn closeFxn
Definition: Capture.h:332
void const * hwAttrs
Definition: Capture.h:370
int_fast16_t Capture_control(Capture_Handle handle, uint_fast16_t cmd, void *arg)
Function performs implementation specific features on a given Capture_Handle.
Capture_ControlFxn controlFxn
Definition: Capture.h:335
struct Capture_Config_ * Capture_Handle
A handle that is returned from a Capture_open() call.
Definition: Capture.h:224
Definition: Capture.h:250
void(* Capture_InitFxn)(Capture_Handle handle)
A function pointer to a driver specific implementation of Capture_init().
Definition: Capture.h:304
Definition: Capture.h:248
int_fast16_t(* Capture_ControlFxn)(Capture_Handle handle, uint_fast16_t cmd, void *arg)
A function pointer to a driver specific implementation of Capture_control().
Definition: Capture.h:297
void(* Capture_CallBackFxn)(Capture_Handle handle, uint32_t interval)
Capture callback function.
Definition: Capture.h:267
Capture_PeriodUnits_
Capture period unit enum.
Definition: Capture.h:246
The definition of a capture function table that contains the required set of functions to control a s...
Definition: Capture.h:330
Capture_FxnTable const * fxnTablePtr
Definition: Capture.h:364
Capture_Mode mode
Definition: Capture.h:278
Capture_StopFxn stopFxn
Definition: Capture.h:347
Capture_InitFxn initFxn
Definition: Capture.h:338
void(* Capture_StopFxn)(Capture_Handle handle)
A function pointer to a driver specific implementation of Capture_stop().
Definition: Capture.h:323
Definition: Capture.h:247
Definition: Capture.h:235
int32_t(* Capture_StartFxn)(Capture_Handle handle)
A function pointer to a driver specific implementation of Capture_start().
Definition: Capture.h:317
void Capture_close(Capture_Handle handle)
Function to close a capture driver instance. The corresponding timer peripheral to Capture_handle bec...
Copyright 2017, Texas Instruments Incorporated