Detailed Description

PWM driver interface.

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

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

Operation

The PWM driver in TI-RTOS facilitates the generation of Pulse Width Modulated signals via simple and portable APIs. A device's PWM peripheral pins must be configured before initializing the PWM driver. The application initializes the PWM driver by calling PWM_init(). PWM instances must be opened by calling PWM_open() while passing in a PWM index and a parameters data structure.

The driver APIs serve as an interface to a typical TI-RTOS application. The specific peripheral implementations are responsible of creating all SYS/BIOS specific primitives to allow for thread-safe operation.

When a PWM instance is opened, the period, units of the duty, and polarity can be set. The maximum period supported is device dependent; refer to the implementation specific documentation for values. A PWM instance can be configured to interpret the duty as one of three units: PWM_DUTY_COUNTS: The duty is in PWM timer ticks. PWM_DUTY_SCALAR: The duty is an integer scaled to the period where 0 corresponds to a duty of 0% and 65535 corresponds to 100% duty. PWM_DUTY_TIME: The duty is specified in microseconds. The driver calculates the appropriate amount of PWM timer ticks.

The polarity is used to set the output during the active duty portion of the period; it can be set to produce low output or a high output when active.

By default PWM output is set to a duty of 0. It is the applications responsability to set the duty for each PWM output used.

Opening the driver

PWM_Handle      handle;
PWM_Params      params;
PWM_Params_init(&params);
params.period = 20000;             // Period in microseconds
params.dutyMode = PWM_DUTY_TIME;   // Duty specified in microseconds
handle = PWM_open(Board_PWM0, &params);
if (handle == NULL) {
    System_printf("PWM did not open");
}
// Update PWM to have a duty of 3000 microseconds
PWM_setDuty(handle, 3000);

Implementation

This module serves as the main interface for TI-RTOS applications. Its purpose is to redirect the module APIs to specific peripheral implementations specified by a pointer to a PWM_FxnTable.

The PWM driver interface module is joined (at link time) to a NULL-terminated array of PWM_Config data structures named PWM_config. PWM_config is implemented in the application with each entry being an instance of a PWM peripheral. Each entry in PWM_config contains a:

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

Currently the following PWM peripheral implementations are supported:

Calling Context

Function	Hwi	Swi	Task	Main
PWM_Params_init	Y	Y	Y	Y
PWM_close	Y	Y	Y	Y
PWM_control	Y	Y	Y	Y
PWM_getPeriodCounts	Y	Y	Y	Y
PWM_getPeriodMicroSecs	Y	Y	Y	Y
PWM_init	Y	Y	Y	Y
PWM_open	Y	Y	Y	Y
PWM_setDuty	Y	Y	Y	Y
Hwi: API is callable from Hwi context. Swi: API is callable from Swi context. Task: API is callable from a Task thread. Main: API is callable from main().

Instrumentation

The PWM 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 <stddef.h>

Include dependency graph for PWM.h:

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

Go to the source code of this file.

Data Structures
struct	PWM_Params
	PWM Parameters. More...

struct	PWM_FxnTable
	The definition of a PWM function table that contains the required set of functions to control a specific PWM driver implementation. More...

struct	PWM_Config
	PWM Global configuration. More...

Macros
#define	PWM_CMD_RESERVED 32

#define	PWM_STATUS_RESERVED -32

#define	PWM_STATUS_SUCCESS 0
	Successful status code returned by PWM_control(). More...

#define	PWM_STATUS_ERROR -1
	Generic error status code returned by PWM_control(). More...

#define	PWM_STATUS_UNDEFINEDCMD -2
	An error status code returned by PWM_control() for undefined command codes. More...

Typedefs
typedef struct PWM_Config *	PWM_Handle
	A handle that is returned from a PWM_open() call. More...

typedef enum PWM_DutyMode	PWM_DutyMode
	Definitions for various units for specifying the PWM duty. More...

typedef enum PWM_Polarity	PWM_Polarity
	Definitions for various PWM output polarity. More...

typedef struct PWM_Params	PWM_Params
	PWM Parameters. More...

typedef void(*	PWM_CloseFxn) (PWM_Handle handle)
	A function pointer to a driver specific implementation of PWM_close(). More...

typedef int(*	PWM_ControlFxn) (PWM_Handle handle, unsigned int cmd, void *arg)
	A function pointer to a driver specific implementation of PWM_control(). More...

typedef unsigned int(*	PWM_GetPeriodCountsFxn) (PWM_Handle handle)
	A function pointer to a driver specific implementation of PWM_getPeriodCounts(). More...

typedef unsigned int(*	PWM_GetPeriodMicroSecsFxn) (PWM_Handle handle)
	A function pointer to a driver specific implementation of PWM_getPeriodMicroSecs(). More...

typedef void(*	PWM_InitFxn) (PWM_Handle handle)
	A function pointer to a driver specific implementation of PWM_init(). More...

typedef PWM_Handle(*	PWM_OpenFxn) (PWM_Handle handle, PWM_Params *params)
	A function pointer to a driver specific implementation of PWM_open(). More...

typedef void(*	PWM_SetDutyFxn) (PWM_Handle handle, uint32_t duty)
	A function pointer to a driver specific implementation of PWM_setDuty(). More...

typedef struct PWM_FxnTable	PWM_FxnTable
	The definition of a PWM function table that contains the required set of functions to control a specific PWM driver implementation. More...

typedef struct PWM_Config	PWM_Config
	PWM Global configuration. More...

Enumerations
enum	PWM_DutyMode { PWM_DUTY_COUNTS = 0, PWM_DUTY_SCALAR, PWM_DUTY_TIME }
	Definitions for various units for specifying the PWM duty. More...

enum	PWM_Polarity { PWM_POL_ACTIVE_HIGH = 0, PWM_POL_ACTIVE_LOW = 1 }
	Definitions for various PWM output polarity. More...

Functions
void	PWM_close (PWM_Handle handle)
	Function to close a PWM peripheral specified by the PWM handle. More...

int	PWM_control (PWM_Handle handle, unsigned int cmd, void *arg)
	Function performs implementation specific features on a given PWM_Handle. More...

unsigned int	PWM_getPeriodCounts (PWM_Handle handle)
	Get the PWM handle period in timer counts. More...

unsigned int	PWM_getPeriodMicroSecs (PWM_Handle handle)
	Get the PWM handle period in microseconds. More...

void	PWM_init (void)
	This function initializes the PWM module. More...

PWM_Handle	PWM_open (unsigned int index, PWM_Params *params)
	This function opens a given PWM peripheral. More...

void	PWM_Params_init (PWM_Params *params)
	Function to initialize the PWM_Params struct to its defaults. More...

void	PWM_setDuty (PWM_Handle handle, uint32_t duty)
	Function to set the duty cycle of the specified PWM handle. More...

Macro Definition Documentation

#define PWM_CMD_RESERVED 32

Common PWM_control command code reservation offset. PWM driver implementations should offset command codes with PWM_CMD_RESERVED growing positively

Example implementation specific command codes:

1 #define PWMXYZ_CMD_COMMAND0 PWM_CMD_RESERVED + 0

2 #define PWMXYZ_CMD_COMMAND1 PWM_CMD_RESERVED + 1

#define PWM_STATUS_RESERVED -32

Common PWM_control status code reservation offset. PWM driver implementations should offset status codes with PWM_STATUS_RESERVED growing negatively.

Example implementation specific status codes:

 #define PWMXYZ_STATUS_ERROR0    PWM_STATUS_RESERVED - 0
 #define PWMXYZ_STATUS_ERROR1    PWM_STATUS_RESERVED - 1
 #define PWMXYZ_STATUS_ERROR2    PWM_STATUS_RESERVED - 2

#define PWM_STATUS_SUCCESS 0

Successful status code returned by PWM_control().

PWM_control() returns PWM_STATUS_SUCCESS if the control code was executed successfully.

#define PWM_STATUS_ERROR -1

Generic error status code returned by PWM_control().

PWM_control() returns PWM_STATUS_ERROR if the control code was not executed successfully.

#define PWM_STATUS_UNDEFINEDCMD -2

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

PWM_control() returns PWM_STATUS_UNDEFINEDCMD if the control code is not recognized by the driver implementation.

Typedef Documentation

typedef struct PWM_Config* PWM_Handle

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

typedef enum PWM_DutyMode PWM_DutyMode

Definitions for various units for specifying the PWM duty.

typedef enum PWM_Polarity PWM_Polarity

Definitions for various PWM output polarity.

typedef struct PWM_Params PWM_Params

PWM Parameters.

PWM Parameters are used to with the PWM_open() call. Default values for these parameters are set using PWM_Params_init().

See also: PWM_Params_init()

typedef void(* PWM_CloseFxn) (PWM_Handle handle)

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

typedef int(* PWM_ControlFxn) (PWM_Handle handle, unsigned int cmd, void *arg)

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

typedef unsigned int(* PWM_GetPeriodCountsFxn) (PWM_Handle handle)

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

typedef unsigned int(* PWM_GetPeriodMicroSecsFxn) (PWM_Handle handle)

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

typedef void(* PWM_InitFxn) (PWM_Handle handle)

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

typedef PWM_Handle(* PWM_OpenFxn) (PWM_Handle handle, PWM_Params *params)

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

typedef void(* PWM_SetDutyFxn) (PWM_Handle handle, uint32_t duty)

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

typedef struct PWM_FxnTable PWM_FxnTable

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

typedef struct PWM_Config PWM_Config

PWM Global configuration.

The PWM_Config structure contains a set of pointers used to characterize the PWM driver implementation.

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

See also: PWM_init()

Enumeration Type Documentation

enum PWM_DutyMode

Definitions for various units for specifying the PWM duty.

Enumerator
PWM_DUTY_COUNTS
PWM_DUTY_SCALAR
PWM_DUTY_TIME

enum PWM_Polarity

Definitions for various PWM output polarity.

Enumerator
PWM_POL_ACTIVE_HIGH	PWM output active high
PWM_POL_ACTIVE_LOW	PWM output active low

Function Documentation

void PWM_close ( PWM_Handle handle )

Function to close a PWM peripheral specified by the PWM handle.

Precondition: PWM_open() has to be called first.

Parameters

handle A PWM handle returned from PWM_open()

See also: PWM_open()

int PWM_control	(	PWM_Handle	handle,
		unsigned int	cmd,
		void *	arg
	)

Function performs implementation specific features on a given PWM_Handle.

Precondition: PWM_open() has to be called first.

Parameters

handle	A PWM handle returned from PWM_open()
cmd	A command value defined by the driver specific implementation
arg	An optional R/W (read/write) argument that is accompanied with cmd

Returns: Implementation specific return codes. Negative values indicate unsuccessful operations.

See also: PWM_open()

unsigned int PWM_getPeriodCounts ( PWM_Handle handle )

Get the PWM handle period in timer counts.

Parameters

handle A PWM_Handle

Returns: Period in timer counts.

See also: PWM_open

unsigned int PWM_getPeriodMicroSecs ( PWM_Handle handle )

Get the PWM handle period in microseconds.

Parameters

handle A PWM_Handle

Returns: Period in microseconds.

See also: PWM_open

void PWM_init ( void )

This function initializes the PWM module.

Precondition: The PWM_config structure must exist and be persistent before this function can be called. This function must also be called before any other PWM driver APIs. This function call does not modify any peripheral registers.

PWM_Handle PWM_open	(	unsigned int	index,
		PWM_Params *	params
	)

This function opens a given PWM peripheral.

Precondition: PWM controller has been initialized using PWM_init()

Parameters

index	Logical peripheral number for the PWM indexed into the PWM_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 PWM_Handle on success or a NULL on an error or if it has been opened already.

See also: PWM_init(); PWM_close()

void PWM_Params_init ( PWM_Params * params )

Function to initialize the PWM_Params struct to its defaults.

Parameters

params An pointer to PWM_Params structure for initialization

Defaults values are: period = 10000 (microseconds) dutyMode = PWM_DUTY_TIME polarity = PWM_POL_ACTIVE_HIGH

void PWM_setDuty	(	PWM_Handle	handle,
		uint32_t	duty
	)

Function to set the duty cycle of the specified PWM handle.

Parameters

handle	A PWM_Handle
duty	PWM duty cycle.

See also: PWM_open

Detailed Description

Operation

Opening the driver

Implementation

Calling Context

Instrumentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation