Data Structures | Macros | Typedefs | Enumerations | Functions
Capture.h File Reference

Detailed Description

Capture driver interface.


The capture header file should be included in an application as follows:

Overview

The capture driver serves as the main interface for a typical RTOS application. Its purpose is to redirect the capture APIs to device specific implementations which are specified using a pointer to a Capture_FxnTable. The device specific implementations are responsible for creating all the RTOS specific primitives to allow for thead-safe operation. The capture driver utilizes the general purpose timer hardware.

The capture driver internally handles the general purpose timer resource allocation. For each capture driver instance, Capture_open() occupies the specified timer, and Capture_close() releases the occupied timer resource.

Usage

The capture driver is used to detect and time edge triggered events on a GPIO pin. The following example code opens a capture instance in falling edge mode. The interval returned in the callback function is in microseconds.

params.callbackFxn = someCaptureCallbackFunction;
handle = Capture_open(someCapture_configIndexValue, &params);
if (handle == NULL) {
//Capture_open() failed
while(1);
}
status = Capture_start(handle);
if (status == Capture_STATUS_ERROR) {
//Capture_start() failed
while(1);
}
sleep(10000);
Capture_stop(handle);

Capture Driver Configuration

In order to use the capture APIs, the application is required to provide device specific capture configuration in the Board.c file. The capture driver interface defines a configuration data structure:

typedef struct Capture_Config_ {
void *object;
void const *hwAttrs;

The application must declare an array of Capture_Config elements, named Capture_config[]. Each element of Capture_config[] is populated with pointers to a device specific capture driver implementation's function table, driver object, and hardware attributes. The hardware attributes define properties such as the timer peripheral's base address, interrupt number and interrupt priority. Each element in Capture_config[] corresponds to a capture instance, and none of the elements should have NULL pointers. There is no correlation between the index and the peripheral designation.

You will need to check the device specific capture driver implementation's header file for example configuration.

Initializing the Capture Driver

Capture_init() must be called before any other capture APIs. This function calls the device implementation's capture initialization function, for each element of Capture_config[].

Modes of Operation

The capture driver supports four modes of operation which may be specified in the Capture_Params.

Capture_RISING_EDGE will capture rising edge triggers. After Capture_start() is called, the callback function specified in Capture_Params will be called after each rising edge is detected on the GPIO pin. This behavior will continue until Capture_stop() is called.

Capture_FALLING_EDGE will capture falling edge triggers. After Capture_start() is called, the callback function specified in Capture_Params will be called after each falling edge is detected on the GPIO pin. This behavior will continue until Capture_stop() is called.

Capture_ANY_EDGE will capture both rising and falling edge triggers. After Capture_start() is called, the callback function specified in Capture_Params will be called after each rising or falling edge is detected on the GPIO pin. This behavior will continue until Capture_stop() is called.

Implementation

The capture driver interface module is joined (at link time) to an array of Capture_Config data structures named Capture_config. Capture_config is implemented in the application with each entry being an instance of a capture peripheral. Each entry in Capture_config contains a:

The capture APIs are redirected to the device specific implementations using the Capture_FxnTable pointer of the Capture_config entry. In order to use device specific functions of the capture driver directly, link in the correct driver library for your device and include the device specific capture driver header file (which in turn includes Capture.h). For example, for the MSP432 family of devices, you would include the following header file:

#include <ti/drivers/capture/CaptureMSP432.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures

struct  Capture_Params_
 Capture Parameters. More...
 
struct  Capture_FxnTable_
 The definition of a capture function table that contains the required set of functions to control a specific capture driver implementation. More...
 
struct  Capture_Config_
 Capture Global configuration. More...
 

Macros

#define Capture_CMD_RESERVED   (32)
 
#define Capture_STATUS_RESERVED   (-32)
 
#define Capture_STATUS_SUCCESS   (0)
 Successful status code. More...
 
#define Capture_STATUS_ERROR   (-1)
 Generic error status code. More...
 
#define Capture_STATUS_UNDEFINEDCMD   (-2)
 An error status code returned by Capture_control() for undefined command codes. More...
 
#define CAPTURE_CMD_RESERVED   Capture_CMD_RESERVED
 
#define CAPTURE_STATUS_RESERVED   Capture_STATUS_RESERVED
 
#define CAPTURE_STATUS_SUCCESS   Capture_STATUS_SUCCESS
 
#define CAPTURE_STATUS_ERROR   Capture_STATUS_ERROR
 
#define CAPTURE_STATUS_UNDEFINEDCMD   Capture_STATUS_UNDEFINEDCMD
 
#define CAPTURE_MODE_RISING_RISING   Capture_RISING_EDGE
 
#define CAPTURE_MODE_FALLING_FALLING   Capture_FALLING_EDGE
 
#define CAPTURE_MODE_ANY_EDGE   Capture_ANY_EDGE
 
#define CAPTURE_PERIOD_US   Capture_PERIOD_US
 
#define CAPTURE_PERIOD_HZ   Capture_PERIOD_HZ
 
#define CAPTURE_PERIOD_COUNTS   Capture_PERIOD_COUNTS
 
#define Capture_Period_Unit   Capture_PeriodUnits
 

Typedefs

typedef struct Capture_Config_Capture_Handle
 A handle that is returned from a Capture_open() call. More...
 
typedef enum Capture_Mode_ Capture_Mode
 Capture mode settings. More...
 
typedef enum Capture_PeriodUnits_ Capture_PeriodUnits
 Capture period unit enum. More...
 
typedef void(* Capture_CallBackFxn) (Capture_Handle handle, uint32_t interval)
 Capture callback function. More...
 
typedef struct Capture_Params_ Capture_Params
 Capture Parameters. More...
 
typedef void(* Capture_CloseFxn) (Capture_Handle handle)
 A function pointer to a driver specific implementation of Capture_close(). More...
 
typedef 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(). More...
 
typedef void(* Capture_InitFxn) (Capture_Handle handle)
 A function pointer to a driver specific implementation of Capture_init(). More...
 
typedef Capture_Handle(* Capture_OpenFxn) (Capture_Handle handle, Capture_Params *params)
 A function pointer to a driver specific implementation of Capture_open(). More...
 
typedef int32_t(* Capture_StartFxn) (Capture_Handle handle)
 A function pointer to a driver specific implementation of Capture_start(). More...
 
typedef void(* Capture_StopFxn) (Capture_Handle handle)
 A function pointer to a driver specific implementation of Capture_stop(). More...
 
typedef struct Capture_FxnTable_ Capture_FxnTable
 The definition of a capture function table that contains the required set of functions to control a specific capture driver implementation. More...
 
typedef struct Capture_Config_ Capture_Config
 Capture Global configuration. More...
 

Enumerations

enum  Capture_Mode_ { Capture_RISING_EDGE, Capture_FALLING_EDGE, Capture_ANY_EDGE }
 Capture mode settings. More...
 
enum  Capture_PeriodUnits_ { Capture_PERIOD_US, Capture_PERIOD_HZ, Capture_PERIOD_COUNTS }
 Capture period unit enum. More...
 

Functions

void Capture_close (Capture_Handle handle)
 Function to close a capture driver instance. The corresponding timer peripheral to Capture_handle becomes an available resource. More...
 
int_fast16_t Capture_control (Capture_Handle handle, uint_fast16_t cmd, void *arg)
 Function performs implementation specific features on a given Capture_Handle. More...
 
void Capture_init (void)
 Function to initialize the capture driver. This function will go through all available hardware resources and mark them as "available". More...
 
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 specifies which mode the capture instance will operate. This function takes care of capture resource allocation. If the particular timer hardware is available to use, the capture driver acquires it and returns a Capture_Handle. More...
 
void Capture_Params_init (Capture_Params *params)
 Function to initialize the Capture_Params struct to its defaults. More...
 
int32_t Capture_start (Capture_Handle handle)
 Function to start the capture instance. More...
 
void Capture_stop (Capture_Handle handle)
 Function to stop a capture instance. If the capture instance is already stopped, this function has no effect. More...
 

Macro Definition Documentation

§ Capture_CMD_RESERVED

#define Capture_CMD_RESERVED   (32)

Common Capture_control command code reservation offset. Capture driver implementations should offset command codes with Capture_CMD_RESERVED growing positively.

Example implementation specific command codes:

#define CaptureXYZ_CMD_COMMAND0 Capture_CMD_RESERVED + 0
#define CaptureXYZ_CMD_COMMAND1 Capture_CMD_RESERVED + 1

§ Capture_STATUS_RESERVED

#define Capture_STATUS_RESERVED   (-32)

Common Capture_control status code reservation offset. Capture driver implementations should offset status codes with Capture_STATUS_RESERVED growing negatively.

Example implementation specific status codes:

#define CaptureXYZ_STATUS_ERROR0 Capture_STATUS_RESERVED - 0
#define CaptureXYZ_STATUS_ERROR1 Capture_STATUS_RESERVED - 1

§ Capture_STATUS_SUCCESS

#define Capture_STATUS_SUCCESS   (0)

Successful status code.

§ Capture_STATUS_ERROR

#define Capture_STATUS_ERROR   (-1)

Generic error status code.

§ Capture_STATUS_UNDEFINEDCMD

#define Capture_STATUS_UNDEFINEDCMD   (-2)

An error status code returned by Capture_control() for undefined command codes.

Capture_control() returns Capture_STATUS_UNDEFINEDCMD if the control code is not recognized by the driver implementation.

§ CAPTURE_CMD_RESERVED

#define CAPTURE_CMD_RESERVED   Capture_CMD_RESERVED

§ CAPTURE_STATUS_RESERVED

#define CAPTURE_STATUS_RESERVED   Capture_STATUS_RESERVED

§ CAPTURE_STATUS_SUCCESS

#define CAPTURE_STATUS_SUCCESS   Capture_STATUS_SUCCESS

§ CAPTURE_STATUS_ERROR

#define CAPTURE_STATUS_ERROR   Capture_STATUS_ERROR

§ CAPTURE_STATUS_UNDEFINEDCMD

#define CAPTURE_STATUS_UNDEFINEDCMD   Capture_STATUS_UNDEFINEDCMD

§ CAPTURE_MODE_RISING_RISING

#define CAPTURE_MODE_RISING_RISING   Capture_RISING_EDGE

§ CAPTURE_MODE_FALLING_FALLING

#define CAPTURE_MODE_FALLING_FALLING   Capture_FALLING_EDGE

§ CAPTURE_MODE_ANY_EDGE

#define CAPTURE_MODE_ANY_EDGE   Capture_ANY_EDGE

§ CAPTURE_PERIOD_US

#define CAPTURE_PERIOD_US   Capture_PERIOD_US

§ CAPTURE_PERIOD_HZ

#define CAPTURE_PERIOD_HZ   Capture_PERIOD_HZ

§ CAPTURE_PERIOD_COUNTS

#define CAPTURE_PERIOD_COUNTS   Capture_PERIOD_COUNTS

§ Capture_Period_Unit

#define Capture_Period_Unit   Capture_PeriodUnits

Typedef Documentation

§ Capture_Handle

A handle that is returned from a Capture_open() call.

§ Capture_Mode

Capture mode settings.

This enum defines the capture modes that may be specified in Capture_Params.

§ Capture_PeriodUnits

Capture period unit enum.

This enum defines the units that may be specified for the period in Capture_Params.

§ Capture_CallBackFxn

typedef void(* Capture_CallBackFxn) (Capture_Handle handle, uint32_t interval)

Capture callback function.

User definable callback function prototype. The capture driver will call the defined function and pass in the capture driver's handle and the pointer to the user-specified the argument.

Parameters
handleCapture_Handle
intervalInterval of two triggering edges in Capture_PeriodUnits

§ Capture_Params

Capture Parameters.

Capture parameters are used by the Capture_open() call. Default values for these parameters are set using Capture_Params_init().

§ Capture_CloseFxn

typedef void(* Capture_CloseFxn) (Capture_Handle handle)

A function pointer to a driver specific implementation of Capture_close().

§ Capture_ControlFxn

typedef 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().

§ Capture_InitFxn

typedef void(* Capture_InitFxn) (Capture_Handle handle)

A function pointer to a driver specific implementation of Capture_init().

§ Capture_OpenFxn

typedef Capture_Handle(* Capture_OpenFxn) (Capture_Handle handle, Capture_Params *params)

A function pointer to a driver specific implementation of Capture_open().

§ Capture_StartFxn

typedef int32_t(* Capture_StartFxn) (Capture_Handle handle)

A function pointer to a driver specific implementation of Capture_start().

§ Capture_StopFxn

typedef void(* Capture_StopFxn) (Capture_Handle handle)

A function pointer to a driver specific implementation of Capture_stop().

§ Capture_FxnTable

The definition of a capture function table that contains the required set of functions to control a specific capture driver implementation.

§ Capture_Config

Capture Global configuration.

The Capture_Config structure contains a set of pointers used to characterize the capture driver implementation.

This structure needs to be defined before calling Capture_init() and it must not be changed thereafter.

See also
Capture_init()

Enumeration Type Documentation

§ Capture_Mode_

Capture mode settings.

This enum defines the capture modes that may be specified in Capture_Params.

Enumerator
Capture_RISING_EDGE 

Capture is triggered on rising edges.

Capture_FALLING_EDGE 

Capture is triggered on falling edges.

Capture_ANY_EDGE 

Capture is triggered on both rising and falling edges.

§ Capture_PeriodUnits_

Capture period unit enum.

This enum defines the units that may be specified for the period in Capture_Params.

Enumerator
Capture_PERIOD_US 

Period specified in micro seconds.

Capture_PERIOD_HZ 

Period specified in hertz; interrupts per second.

Capture_PERIOD_COUNTS 

Period specified in timer ticks. Varies by board.

Function Documentation

§ Capture_close()

void Capture_close ( Capture_Handle  handle)

Function to close a capture driver instance. The corresponding timer peripheral to Capture_handle becomes an available resource.

Precondition
Capture_open() has been called.
Parameters
handleA Capture_Handle returned from Capture_open().
See also
Capture_open()

§ Capture_control()

int_fast16_t Capture_control ( Capture_Handle  handle,
uint_fast16_t  cmd,
void *  arg 
)

Function performs implementation specific features on a given Capture_Handle.

Precondition
Capture_open() has been called.
Parameters
handleA Capture_Handle returned from Capture_open().
cmdA command value defined by the driver specific implementation.
argA pointer to an optional R/W (read/write) argument that is accompanied with cmd.
Returns
A Capture_Status describing an error or success state. Negative values indicate an error occurred.
See also
Capture_open()

§ Capture_init()

void Capture_init ( void  )

Function to initialize the capture driver. This function will go through all available hardware resources and mark them as "available".

Precondition
The Capture_config structure must exist and be persistent before this function can be called. This function must also be called before any other capture driver APIs.
See also
Capture_open()

§ Capture_open()

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 specifies which mode the capture instance will operate. This function takes care of capture resource allocation. If the particular timer hardware is available to use, the capture driver acquires it and returns a Capture_Handle.

Precondition
Capture_init() has been called.
Parameters
indexLogical instance number for the capture indexed into the Capture_config table.
paramsPointer to a parameter block. Cannot be NULL.
Returns
A Capture_Handle on success, or NULL if the timer peripheral is already in use.
See also
Capture_init()
Capture_close()

§ Capture_Params_init()

void Capture_Params_init ( Capture_Params params)

Function to initialize the Capture_Params struct to its defaults.

Parameters
paramsAn pointer to Capture_Params structure for initialization.

Defaults values are: callbackFxn = NULL mode = Capture_RISING_EDGE periodUnit = Capture_PERIOD_COUNTS

§ Capture_start()

int32_t Capture_start ( Capture_Handle  handle)

Function to start the capture instance.

Precondition
Capture_open() has been called.
Parameters
handleA Capture_Handle returned from Capture_open().
Returns
Capture_STATUS_SUCCESS or Capture_STATUS_ERROR.
See also
Capture_stop().

§ Capture_stop()

void Capture_stop ( Capture_Handle  handle)

Function to stop a capture instance. If the capture instance is already stopped, this function has no effect.

Precondition
Capture_open() has been called.
Parameters
handleA Capture_Handle returned from Capture_open().
See also
Capture_start()
Copyright 2017, Texas Instruments Incorporated