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.

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(Board_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);

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_ {
    Capture_FxnTable const *fxnTablePtr;
    void                   *object;
    void             const *hwAttrs;
} Capture_Config;

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:

(Capture_FxnTable *) to a set of functions that implement a capture peripheral
(void *) data object that is associated with the Capture_FxnTable
(void *) hardware attributes that are associated with the Capture_FxnTable

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>

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

#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

typedef struct Capture_Config_* Capture_Handle

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

§ Capture_Mode

typedef enum Capture_Mode_ Capture_Mode

Capture mode settings.

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

§ Capture_PeriodUnits

typedef enum Capture_PeriodUnits_ 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

handle	Capture_Handle
interval	Interval of two triggering edges in Capture_PeriodUnits

§ Capture_Params

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

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.

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

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_

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.

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

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

handle	A Capture_Handle returned from Capture_open().
cmd	A command value defined by the driver specific implementation.
arg	A 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

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

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

handle A 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

handle A Capture_Handle returned from Capture_open().

See also: Capture_start()

Detailed Description

Overview

Usage

Capture Driver Configuration

Initializing the Capture Driver

Modes of Operation

Implementation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ Capture_CMD_RESERVED

§ Capture_STATUS_RESERVED

§ Capture_STATUS_SUCCESS

§ Capture_STATUS_ERROR

§ Capture_STATUS_UNDEFINEDCMD

§ CAPTURE_CMD_RESERVED

§ CAPTURE_STATUS_RESERVED

§ CAPTURE_STATUS_SUCCESS

§ CAPTURE_STATUS_ERROR

§ CAPTURE_STATUS_UNDEFINEDCMD

§ CAPTURE_MODE_RISING_RISING

§ CAPTURE_MODE_FALLING_FALLING

§ CAPTURE_MODE_ANY_EDGE

§ CAPTURE_PERIOD_US

§ CAPTURE_PERIOD_HZ

§ CAPTURE_PERIOD_COUNTS

§ Capture_Period_Unit

Typedef Documentation

§ Capture_Handle

§ Capture_Mode

§ Capture_PeriodUnits

§ Capture_CallBackFxn

§ Capture_Params

§ Capture_CloseFxn

§ Capture_ControlFxn

§ Capture_InitFxn

§ Capture_OpenFxn

§ Capture_StartFxn

§ Capture_StopFxn

§ Capture_FxnTable

§ 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()