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

Detailed Description

Pulse Width Modulation (PWM) driver.


Overview

The PWM driver in TI-RTOS facilitates the generation of Pulse Width Modulated signals via simple and portable APIs.

When a PWM instance is opened, the period, duty cycle and idle level are configured and the PWM is stopped (waveforms not generated until PWM_start() is called). The maximum period and duty supported is device dependent; refer to the implementation specific documentation for values.

PWM outputs are active-high, meaning the duty will control the duration of high output on the pin (at 0% duty, the output is always low, at 100% duty, the output is always high).


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 PWM Driver definitions
#include <ti/drivers/PWM.h>
PWM_Params pwmParams;
uint32_t dutyValue;
// Initialize the PWM driver.
// Initialize the PWM parameters
PWM_Params_init(&pwmParams);
pwmParams.idleLevel = PWM_IDLE_LOW; // Output low when PWM is not running
pwmParams.periodUnits = PWM_PERIOD_HZ; // Period is in Hz
pwmParams.periodValue = 1e6; // 1MHz
pwmParams.dutyUnits = PWM_DUTY_FRACTION; // Duty is in fractional percentage
pwmParams.dutyValue = 0; // 0% initial duty cycle
// Open the PWM instance
pwm = PWM_open(Board_PWM0, &pwmParams);
if (pwm == NULL) {
// PWM_open() failed
while (1);
}
PWM_start(pwm); // start PWM with 0% duty cycle
dutyValue = (uint32_t) (((uint64_t) PWM_DUTY_FRACTION_MAX * 37) / 100);
PWM_setDuty(pwm, dutyValue); // set duty cycle to 37%

Examples

Opening a PWM instance

PWM_Params pwmParams;
PWM_Params_init(&pwmParams);
pwmParams.idleLevel = PWM_IDLE_LOW;
pwmParams.periodValue = 1e6;
pwmParams.dutyValue = 0;
pwm = PWM_open(Board_PWM0, &pwmParams);
if (pwm == NULL) {
// PWM_open() failed
while (1);
}

Setting PWM duty

Once the PWM instance has been opened and started, the primary API used by the application will be PWM_setDuty() to control the duty cycle of a PWM pin:

Below demonstrates setting the duty cycle to 45%.

uint32_t dutyCycle;
dutyCycle = (uint32_t) (((uint64_t) PWM_DUTY_FRACTION_MAX * 45) / 100);
PWM_setDuty(pwm, dutyCycle);

Setting PWM Duty and Period

If an application needs to modify the duty and period of a running timer, an API is available to set both with as little interim time as possible. This minimises the possibility that a timeout will occur between one set call and the other. For low periods or for instances close to timeout, this API will pause the instance output briefly and must only be called when the PWM is already running.

Below demonstrates setting the duty cycle to 75% of the new period (100us).

uint32_t dutyCycle;
uint32_t periodUs = 100;
dutyCycle = (uint32_t) (((uint64_t) PWM_DUTY_FRACTION_MAX * 75) / 100);
PWM_setDutyAndPeriod(pwm, dutyCycle, periodUs);

Modes of Operation

A PWM instance can be configured to interpret the period as one of three units:

A PWM instance can be configured to interpret the duty as one of three units:

The idle level parameter is used to set the output to high/low when the PWM is not running (stopped or not started). The idle level can be set to:

The default PWM configuration is to set a duty of 0% with a 1MHz frequency. The default period units are in PWM_PERIOD_HZ and the default duty units are in PWM_DUTY_FRACTION. Finally, the default output idle level is PWM_IDLE_LOW. It is the application's responsibility to set the duty for each PWM output used.


Configuration

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


#include <stdint.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_DUTY_FRACTION_MAX   ((uint32_t) ~0)
 Maximum duty (100%) when configuring duty cycle as a fraction of period. More...
 
#define PWM_CMD_RESERVED   (32)
 
#define PWM_STATUS_RESERVED   (-32)
 
#define PWM_STATUS_SUCCESS   (0)
 Success status code returned by: PWM_control(), PWM_setDuty(), PWM_setPeriod(). 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...
 
#define PWM_STATUS_INVALID_PERIOD   (-3)
 An error status code returned by PWM_setPeriod(). More...
 
#define PWM_STATUS_INVALID_DUTY   (-4)
 An error status code returned by PWM_setDuty(). More...
 

Typedefs

typedef struct PWM_Config_PWM_Handle
 A handle that is returned from a PWM_open() call. More...
 
typedef void(* PWM_CloseFxn) (PWM_Handle handle)
 A function pointer to a driver specific implementation of PWM_close(). More...
 
typedef int_fast16_t(* PWM_ControlFxn) (PWM_Handle handle, uint_fast16_t cmd, void *arg)
 A function pointer to a driver specific implementation of PWM_control(). 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 int_fast16_t(* PWM_SetDutyFxn) (PWM_Handle handle, uint32_t duty)
 A function pointer to a driver specific implementation of PWM_setDuty(). More...
 
typedef int_fast16_t(* PWM_SetPeriodFxn) (PWM_Handle handle, uint32_t period)
 A function pointer to a driver specific implementation of PWM_setPeriod(). More...
 
typedef int_fast16_t(* PWM_SetDutyAndPeriodFxn) (PWM_Handle handle, uint32_t duty, uint32_t period)
 A function pointer to a driver specific implementation of PWM_setDutyAndPeriod(). More...
 
typedef void(* PWM_StartFxn) (PWM_Handle handle)
 A function pointer to a driver specific implementation of PWM_start(). More...
 
typedef void(* PWM_StopFxn) (PWM_Handle handle)
 A function pointer to a driver specific implementation of PWM_stop(). 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_Period_Units { PWM_PERIOD_US, PWM_PERIOD_HZ, PWM_PERIOD_COUNTS }
 PWM period unit definitions. Refer to device specific implementation if using PWM_PERIOD_COUNTS (raw PWM/Timer counts). More...
 
enum  PWM_Duty_Units { PWM_DUTY_US, PWM_DUTY_FRACTION, PWM_DUTY_COUNTS }
 PWM duty cycle unit definitions. Refer to device specific implementation if using PWM_DUTY_COUNTS (raw PWM/Timer counts). More...
 
enum  PWM_IdleLevel { PWM_IDLE_LOW = 0, PWM_IDLE_HIGH = 1 }
 Idle output level when PWM is not running (stopped / not started). More...
 

Functions

void PWM_close (PWM_Handle handle)
 Function to close a PWM instance specified by the PWM handle. More...
 
int_fast16_t PWM_control (PWM_Handle handle, uint_fast16_t cmd, void *arg)
 Function performs implementation specific features on a given PWM_Handle. More...
 
void PWM_init (void)
 This function initializes the PWM module. More...
 
PWM_Handle PWM_open (uint_least8_t index, PWM_Params *params)
 This function opens a given PWM instance and sets the period, duty and idle level to those specified in the params argument. More...
 
void PWM_Params_init (PWM_Params *params)
 Function to initialize the PWM_Params structure to default values. More...
 
int_fast16_t PWM_setDuty (PWM_Handle handle, uint32_t duty)
 Function to set the duty cycle of the specified PWM handle. PWM instances run in active high output mode; 0% is always low output, 100% is always high output. This API can be called while the PWM is running & duty must always be lower than or equal to the period. If an error occurs while calling the function the PWM duty cycle will remain unchanged. More...
 
int_fast16_t PWM_setPeriod (PWM_Handle handle, uint32_t period)
 Function to set the period of the specified PWM handle. This API can be called while the PWM is running & the period must always be larger than the duty cycle. If an error occurs while calling the function the PWM period will remain unchanged. More...
 
int_fast16_t PWM_setDutyAndPeriod (PWM_Handle handle, uint32_t duty, uint32_t period)
 Function to set both the period and the duty cycle of the specified PWM handle. This API must be called while the PWM is running & the period must always be larger than the duty cycle. If an error occurs while calling the function the period and duty will remain unchanged. More...
 
void PWM_start (PWM_Handle handle)
 Function to start the specified PWM handle with current settings. More...
 
void PWM_stop (PWM_Handle handle)
 Function to stop the specified PWM handle. Output will set to the idle level specified by params in PWM_open(). More...
 

Macro Definition Documentation

§ PWM_DUTY_FRACTION_MAX

#define PWM_DUTY_FRACTION_MAX   ((uint32_t) ~0)

Maximum duty (100%) when configuring duty cycle as a fraction of period.

§ PWM_CMD_RESERVED

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

#define PWMXYZ_COMMAND0 (PWM_CMD_RESERVED + 0)
#define PWMXYZ_COMMAND1 (PWM_CMD_RESERVED + 1)

§ PWM_STATUS_RESERVED

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

§ PWM_STATUS_SUCCESS

#define PWM_STATUS_SUCCESS   (0)

Success status code returned by: PWM_control(), PWM_setDuty(), PWM_setPeriod().

Functions return PWM_STATUS_SUCCESS if the call was executed successfully.

§ PWM_STATUS_ERROR

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

§ PWM_STATUS_UNDEFINEDCMD

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

§ PWM_STATUS_INVALID_PERIOD

#define PWM_STATUS_INVALID_PERIOD   (-3)

An error status code returned by PWM_setPeriod().

PWM_setPeriod() returns PWM_STATUS_INVALID_PERIOD if the period argument is invalid for the current configuration.

§ PWM_STATUS_INVALID_DUTY

#define PWM_STATUS_INVALID_DUTY   (-4)

An error status code returned by PWM_setDuty().

PWM_setDuty() returns PWM_STATUS_INVALID_DUTY if the duty cycle argument is invalid for the current configuration.

Typedef Documentation

§ PWM_Handle

typedef struct PWM_Config_* PWM_Handle

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

§ PWM_CloseFxn

typedef void(* PWM_CloseFxn) (PWM_Handle handle)

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

§ PWM_ControlFxn

typedef int_fast16_t(* PWM_ControlFxn) (PWM_Handle handle, uint_fast16_t cmd, void *arg)

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

§ PWM_InitFxn

typedef void(* PWM_InitFxn) (PWM_Handle handle)

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

§ PWM_OpenFxn

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

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

§ PWM_SetDutyFxn

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

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

§ PWM_SetPeriodFxn

typedef int_fast16_t(* PWM_SetPeriodFxn) (PWM_Handle handle, uint32_t period)

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

§ PWM_SetDutyAndPeriodFxn

typedef int_fast16_t(* PWM_SetDutyAndPeriodFxn) (PWM_Handle handle, uint32_t duty, uint32_t period)

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

§ PWM_StartFxn

typedef void(* PWM_StartFxn) (PWM_Handle handle)

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

§ PWM_StopFxn

typedef void(* PWM_StopFxn) (PWM_Handle handle)

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

§ PWM_FxnTable

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.

§ PWM_Config

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.

Enumeration Type Documentation

§ PWM_Period_Units

PWM period unit definitions. Refer to device specific implementation if using PWM_PERIOD_COUNTS (raw PWM/Timer counts).

Enumerator
PWM_PERIOD_US 

Period in microseconds

PWM_PERIOD_HZ 

Period in (reciprocal) Hertz (for example 2MHz = 0.5us period)

PWM_PERIOD_COUNTS 

Period in timer counts

§ PWM_Duty_Units

PWM duty cycle unit definitions. Refer to device specific implementation if using PWM_DUTY_COUNTS (raw PWM/Timer counts).

Enumerator
PWM_DUTY_US 

Duty cycle in microseconds

PWM_DUTY_FRACTION 

Duty as a fractional part of PWM_DUTY_FRACTION_MAX. A duty cycle value of 0 will yield a 0% duty cycle while a duty cycle value of PWM_DUTY_FRACTION_MAX will yield a duty cycle value of 100%.

PWM_DUTY_COUNTS 

Duty in timer counts

§ PWM_IdleLevel

Idle output level when PWM is not running (stopped / not started).

Enumerator
PWM_IDLE_LOW 
PWM_IDLE_HIGH 

Function Documentation

§ PWM_close()

void PWM_close ( PWM_Handle  handle)

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

Precondition
PWM_open() must have been called first.
PWM_stop() must have been called first if PWM was started.
Parameters
[in]handleA PWM handle returned from PWM_open().
See also
PWM_open()
PWM_start()
PWM_stop()

§ PWM_control()

int_fast16_t PWM_control ( PWM_Handle  handle,
uint_fast16_t  cmd,
void *  arg 
)

Function performs implementation specific features on a given PWM_Handle.

Precondition
PWM_open() must have been called first.
Parameters
[in]handleA PWM handle returned from PWM_open().
[in]cmdA command value defined by the driver specific implementation.
[in]argA pointer to an optional R/W (read/write) argument that is accompanied with cmd.
Return values
PWM_STATUS_SUCCESSThe control call was successful.
PWM_STATUS_ERRORThe control call failed.
See also
PWM_open()

§ PWM_init()

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 be called before any other PWM driver APIs. This function does not modify any peripheral registers & should only be called once.

§ PWM_open()

PWM_Handle PWM_open ( uint_least8_t  index,
PWM_Params params 
)

This function opens a given PWM instance and sets the period, duty and idle level to those specified in the params argument.

Parameters
[in]indexLogical instance number for the PWM indexed into the PWM_config table.
[in]paramsPointer to an parameter structure. If NULL default values are used.
Returns
A PWM_Handle if successful or NULL on an error or if it has been opened already. If NULL is returned further PWM API calls will result in undefined behavior.
See also
PWM_close()

§ PWM_Params_init()

void PWM_Params_init ( PWM_Params params)

Function to initialize the PWM_Params structure to default values.

Parameters
[in]paramsA pointer to PWM_Params structure for initialization.

Defaults values are: Period units: PWM_PERIOD_HZ Period: 1e6 (1MHz) Duty cycle units: PWM_DUTY_FRACTION Duty cycle: 0% Idle level: PWM_IDLE_LOW

§ PWM_setDuty()

int_fast16_t PWM_setDuty ( PWM_Handle  handle,
uint32_t  duty 
)

Function to set the duty cycle of the specified PWM handle. PWM instances run in active high output mode; 0% is always low output, 100% is always high output. This API can be called while the PWM is running & duty must always be lower than or equal to the period. If an error occurs while calling the function the PWM duty cycle will remain unchanged.

Precondition
PWM_open() must have been called first.
Parameters
[in]handleA PWM handle returned from PWM_open().
[in]dutyDuty cycle in the units specified by the params used in PWM_open().
Return values
PWM_STATUS_SUCCESSThe duty was set successfully.
PWM_STATUS_ERRORThe duty was not set and remains unchanged.
See also
PWM_open()

§ PWM_setPeriod()

int_fast16_t PWM_setPeriod ( PWM_Handle  handle,
uint32_t  period 
)

Function to set the period of the specified PWM handle. This API can be called while the PWM is running & the period must always be larger than the duty cycle. If an error occurs while calling the function the PWM period will remain unchanged.

Precondition
PWM_open() must have been called first.
Parameters
[in]handleA PWM handle returned from PWM_open().
[in]periodPeriod in the units specified by the params used in PWM_open().
Return values
PWM_STATUS_SUCCESSThe period was set successfully.
PWM_STATUS_ERRORThe period was not set and remains unchanged.
See also
PWM_open()

§ PWM_setDutyAndPeriod()

int_fast16_t PWM_setDutyAndPeriod ( PWM_Handle  handle,
uint32_t  duty,
uint32_t  period 
)

Function to set both the period and the duty cycle of the specified PWM handle. This API must be called while the PWM is running & the period must always be larger than the duty cycle. If an error occurs while calling the function the period and duty will remain unchanged.

Note
This API should only be called while the PWM is running.
If the period is lower than a certain platform-specific amount, the output of the PWM timer may be paused to set these values. Some implementations may also pause the PWM if the remaining time before the next timeout is less than this value. This is to guard against an edge case where a timeout happens in between setting period and duty.
Precondition
PWM_open() must have been called first.
Parameters
[in]handleA PWM handle returned from PWM_open().
[in]dutyDuty cycle in the units specified by the params used in PWM_open().
[in]periodPeriod in the units specified by the params used in PWM_open().
Return values
PWM_STATUS_SUCCESSThe duty and period was set successfully.
PWM_STATUS_ERRORThe duty and period was not set and remains unchanged.
See also
PWM_open()

§ PWM_start()

void PWM_start ( PWM_Handle  handle)

Function to start the specified PWM handle with current settings.

Precondition
PWM_open() has to have been called first.
Parameters
[in]handleA PWM handle returned from PWM_open().
See also
PWM_open()
PWM_stop()

§ PWM_stop()

void PWM_stop ( PWM_Handle  handle)

Function to stop the specified PWM handle. Output will set to the idle level specified by params in PWM_open().

Precondition
PWM_open() has to have been called first.
Parameters
[in]handleA PWM handle returned from PWM_open().
See also
PWM_open()
PWM_start()
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale