Detailed Description

Capture driver interface.

============================================================================

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

Operation

The Capture driver facilitates the capture routines by using general purpose timers. Capture instances must be opened by calling Capture_open() while passing in a Capture index and parameters data structure.

When a capture instance is opened, the capture triggering edge and callback function are configured. The capture is stopped after calling Capture_open() until Capture_start() is called.

When Capture_open() is called, it tries to occupy the user-specified timer by calling Timer_open(). If that timer is already allocated for other modules, NULL is returned. Otherwise, the Capture_Handle is returned.

A capture is triggered based on the user-specified capture mode:

CAPTURE_MODE_RISING_RISING
CAPTURE_MODE_RISING_FALLING
CAPTURE_MODE_ANY_EDGE The user-specified callback function is called once the input signal matches the capture mode and the value passed into callback function is the interval between two triggering edge in the user-specified unit.

opening the driver

Capture_Handle      handle;
Capture_Params      params;
Capture_Params_init(&params);
params.mode  = CAPTURE_MODE_RISING_FALLING;
params.callbackFxn = someCaptureCallbackFunction;
params.periodUnit = CAPTURE_PERIOD_US;
handle = Capture_open(someCapture_configIndexValue, &params);
if (!handle)
{
    System_printf("Capture did not open");
}
## starting the driver ##
@code
status = Capture_start(handle);
if (status == Capture_STATUS_ERROR)
{
    System_printf("Capture cannot start");
}

stoping the driver

Capture_stop(handle);

closing the driver

Capture_close(handle);

Implementation

This module serves as the main interface for TI-RTOS applications. Its purpose is to redirect the module's APIs to specific peripheral implementations which are specified using a pointer to a Capture_FxnTable.

The Capture driver interface module is joined (at link time) to a NULL-terminated 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 module. Each entry in Capture_Config contains a:

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

Instrumentation

The Capture driver interface produces log statements if instrumentation is enabled.

Diagnostics Mask	Log details
Diags_USER1	basic operations performed
Diags_USER2	detailed operations performed

#include <stdint.h>
#include <stdbool.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_

Macros
#define	CAPTURE_CMD_RESERVED (32)

#define	CAPTURE_STATUS_RESERVED (-32)

#define	CAPTURE_STATUS_SUCCESS (0)
	Successful status code returned by Capture_control(). More...

#define	CAPTURE_STATUS_ERROR (-1)
	Generic error status code returned by Capture_control(). 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 enum Capture_Period_Unit_	Capture_Period_Unit
	Capture period unit enum. More...

typedef enum Capture_Mode_	Capture_Mode
	Capture mode 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 void(*	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

Enumerations
enum	Capture_Period_Unit_ { CAPTURE_PERIOD_US, CAPTURE_PERIOD_HZ, CAPTURE_PERIOD_COUNTS }
	Capture period unit enum. More...

enum	Capture_Mode_ { CAPTURE_MODE_RISING_RISING, CAPTURE_MODE_FALLING_FALLING, CAPTURE_MODE_ANY_EDGE }
	Capture mode enum. More...

Functions
void	Capture_close (Capture_Handle handle)
	Function to close a Capture module specified by the Capture handle. 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 Capture. More...

Capture_Handle	Capture_open (uint_least8_t index, Capture_Params *params)
	Function to initialize a given Capture module specified by the particular index value. The parameter specifies which mode the Capture will operate. More...

void	Capture_Params_init (Capture_Params *params)
	Function to initialize the Capture_Params struct to its defaults. More...

void	Capture_start (Capture_Handle handle)
	Function to start capture. The Capture running mode and interval period unit are specfied in the Capture_Params when calling Capture_open(). More...

void	Capture_stop (Capture_Handle handle)
	Function to stop Capture after Capture_start() is called with success. More...

Macro Definition Documentation

#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:

1 #define CAPTUREXYZ_CMD_COMMAND0 CAPTURE_CMD_RESERVED + 0

2 #define CAPTUREXYZ_CMD_COMMAND1 CAPTURE_CMD_RESERVED + 1

#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
 #define CAPTUREXYZ_STATUS_ERROR2     CAPTURE_STATUS_RESERVED - 2

#define CAPTURE_STATUS_SUCCESS (0)

Successful status code returned by Capture_control().

Capture_control() returns TIMER_STATUS_SUCCESS if the control code was executed successfully.

#define CAPTURE_STATUS_ERROR (-1)

Generic error status code returned by Capture_control().

Capture_control() returns CAPTURE_STATUS_ERROR if the control code was not executed successfully.

#define CAPTURE_STATUS_UNDEFINEDCMD (-2)

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

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

Typedef Documentation

typedef struct Capture_Config_* Capture_Handle

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

typedef enum Capture_Period_Unit_ Capture_Period_Unit

Capture period unit enum.

The Capture period unit needs to be passed in Capture_open() to specify the unit of two capture triggering interval.

typedef enum Capture_Mode_ Capture_Mode

Capture mode enum.

The Capture mode needs to be passed in Capture_open() to specify the capture triggering mode.

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 edge in Capture_Period_Unit

typedef struct Capture_Params_ Capture_Params

Capture Parameters.

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

typedef void(* Capture_CloseFxn) (Capture_Handle handle)

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

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

typedef void(* Capture_InitFxn) (Capture_Handle handle)

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

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

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

typedef void(* Capture_StartFxn) (Capture_Handle handle)

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

typedef void(* Capture_StopFxn) (Capture_Handle handle)

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

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.

typedef struct Capture_Config_ Capture_Config

Enumeration Type Documentation

enum Capture_Period_Unit_

Capture period unit enum.

The Capture period unit needs to be passed in Capture_open() to specify the unit of two capture triggering interval.

Enumerator
CAPTURE_PERIOD_US
CAPTURE_PERIOD_HZ
CAPTURE_PERIOD_COUNTS

enum Capture_Mode_

Capture mode enum.

The Capture mode needs to be passed in Capture_open() to specify the capture triggering mode.

Enumerator
CAPTURE_MODE_RISING_RISING	capture is triggered at the rising edge followed by the rising edge
CAPTURE_MODE_FALLING_FALLING	capture is triggered at the falling edge followed by the falling edge
CAPTURE_MODE_ANY_EDGE	capture is triggered at the falling edge followed by the rising edge

Function Documentation

void Capture_close ( Capture_Handle handle )

Function to close a Capture module specified by the Capture handle.

The function takes care of timer resource allocation. The corresponding timer resource to the Capture_Handle is released to be an available timer resource.

Precondition: Capture_open() had to be called first.

Parameters

handle A Capture_Handle returned from Capture_open

See also: Capture_open()

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() must have been called first.

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

void Capture_init ( void )

Function to initialize Capture.

Capture_Handle Capture_open	(	uint_least8_t	index,
		Capture_Params *	params
	)

Function to initialize a given Capture module specified by the particular index value. The parameter specifies which mode the Capture will operate.

The function takes care of timer resource allocation. If the particular timer passed by user has already been used by other modules, the return value is NULL. If the particular timer is available to use, Capture module owns it and returns a Capture_Handle.

Parameters

index	Logical instance number for the Capture indexed into the Capture_config table
params	Pointer to an parameter block, if NULL it will use default values. All the fields in this structure are RO (read-only).

Returns: A Capture_Handle on success or a NULL on an error if it has been opened already or used by other modules.

See also: Capture_init(); Capture_close()

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: mode = CAPTURE_MODE_RISING_RISING callbackFxn = user_specified_callbackFxn periodUnit = Capture_PERIOD_COUNTS

void Capture_start ( Capture_Handle handle )

Function to start capture. The Capture running mode and interval period unit are specfied in the Capture_Params when calling Capture_open().

Parameters

handle Capture_Handle

Returns: CAPTURE_STATUS_SUCCESS if Capture starts successfully. CAPTURE_STATUS_ERROR if Capture fails to start.

void Capture_stop ( Capture_Handle handle )

Function to stop Capture after Capture_start() is called with success.

Parameters

handle Capture_Handle

Detailed Description

Operation

opening the driver

stoping the driver

closing the driver

Implementation

Instrumentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation