Detailed Description

Capture Driver.

Overview

The capture driver is used to detect and time edge triggered events on a GPIO pin.

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

This documentation provides a basic usage summary and a set of examples in the form of commented code fragments. Detailed descriptions of the APIs are provided in subsequent sections.

Synopsis

// Import Capture Driver definitions
#include <ti/drivers/Capture.h>
Capture_Handle    handle;
Capture_Params    params;
Capture_Params_init(&params);
params.mode  = Capture_FALLING_EDGE;
params.callbackFxn = someCaptureCallbackFunction;
params.periodUnit = Capture_PERIOD_US;
handle = Capture_open(CONFIG_CAPTURE0, &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);

Examples

Opening a Capture instance

Opening a Capture instance

Capture_Handle  handle;
Capture_Params  params;
Capture_Params_init(&params);
params.mode  = Capture_FALLING_EDGE;
params.callbackFxn = someCaptureCallbackFunction;
params.periodUnit = Capture_PERIOD_US;
handle = Capture_open(CONFIG_CAPTURE0, &params);
if (handle == NULL) {
    //Capture_open() failed
    while(1);
}

Configuration

Refer to the Driver's Configuration section for driver configuration information.

#include <stdint.h>

Include dependency graph for Capture.h:

This graph shows which files directly or indirectly include this file:

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...

Typedefs
typedef struct Capture_Config_ *	Capture_Handle
	A handle that is returned from a Capture_open() call. More...

typedef void(*	Capture_CallBackFxn) (Capture_Handle handle, uint32_t interval)
	Capture callback function. 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_Config_	Capture_Config
	Capture Global configuration. More...

Enumerations
enum	Capture_Mode { Capture_RISING_EDGE, Capture_FALLING_EDGE, Capture_ANY_EDGE, Capture_RISING_EDGE_FALLING_EDGE, Capture_FALLING_EDGE_RISING_EDGE }
	Capture mode settings. More...

enum	Capture_PeriodUnits { Capture_PERIOD_US, Capture_PERIOD_HZ, Capture_PERIOD_COUNTS, Capture_PERIOD_NS }
	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.

Typedef Documentation

§ Capture_Handle

typedef struct Capture_Config_* Capture_Handle

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

§ 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

[in]	handle	Capture_Handle
[in]	interval	Interval of two triggering edges in Capture_PeriodUnits

§ 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_Config

typedef struct Capture_Config_ 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

enum Capture_Mode

Capture mode settings.

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

Some modes are not available on all devices. Check the device specific implementations to see which modes are allowed.

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_RISING_EDGE_FALLING_EDGE	Start capture is triggered on rising edge and stop capture is triggered on falling edge
Capture_FALLING_EDGE_RISING_EDGE	Start capture is triggered on falling edge and stop capture is triggered on rising edge

§ Capture_PeriodUnits

enum 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.
Capture_PERIOD_NS	Period specified in nano seconds.

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

[in] handle A 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

[in]	handle	A Capture_Handle returned from Capture_open().
[in]	cmd	A command value defined by the driver specific implementation.
[in]	arg	A pointer to an optional R/W (read/write) argument that is accompanied with cmd.

Return values

Capture_STATUS_SUCCESS	The control call was successful.
Capture_STATUS_ERROR	The control call failed.

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

[in]	index	Logical instance number for the capture indexed into the Capture_config table.
[in]	params	Pointer 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

[in] params An 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

[in] handle A Capture_Handle returned from Capture_open().

Return values

Capture_STATUS_SUCCESS	The start call was successful.
Capture_STATUS_ERROR	The start call failed.

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

[in] handle A Capture_Handle returned from Capture_open().

See also: Capture_start()

Detailed Description

Overview

Usage

Synopsis

Examples

Opening a Capture instance

Configuration

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ Capture_CMD_RESERVED

§ Capture_STATUS_RESERVED

§ Capture_STATUS_SUCCESS

§ Capture_STATUS_ERROR

§ Capture_STATUS_UNDEFINEDCMD

Typedef Documentation

§ Capture_Handle

§ Capture_CallBackFxn

§ Capture_CloseFxn

§ Capture_ControlFxn

§ Capture_InitFxn

§ Capture_OpenFxn

§ Capture_StartFxn

§ Capture_StopFxn

§ Capture_Config

Enumeration Type Documentation

§ Capture_Mode

§ Capture_PeriodUnits

Function Documentation

§ Capture_close()

§ Capture_control()

§ Capture_init()

§ Capture_open()

§ Capture_Params_init()

§ Capture_start()

§ Capture_stop()