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

Detailed Description

PWM driver interface.


To use the PWM driver, ensure that the correct driver library for your device is linked in and include this header file as follows:

#include <ti/drivers/PWM.h>

This module serves as the main interface for applications. Its purpose is to redirect the PWM APIs to specific driver implementations which are specified using a pointer to a PWM_FxnTable.

Overview

The PWM driver in TI-RTOS facilitates the generation of Pulse Width Modulated signals via simple and portable APIs. 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 for creating all OS specific primitives to allow for thread-safe operation.

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

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%

Details for the example code above are described in the following subsections.

PWM Driver Configuration

In order to use the PWM APIs, the application is required to provide device-specific PWM configuration in the Board.c file. The PWM driver interface defines a configuration data structure:

typedef struct PWM_Config_ {
void *object;
void const *hwAttrs;

The application must declare an array of PWM_Config elements, named PWM_config[]. Each element of PWM_config[] is populated with pointers to a device specific PWM driver implementation's function table, driver object, and hardware attributes. The hardware attributes define properties such as which pin will be driven, and which timer peripheral will be used. Each element in PWM_config[] corresponds to a PWM instance, and none of the elements should have NULL pointers.

Additionally, the PWM driver interface defines a global integer variable 'PWM_count' which is initialized to the number of PWM instances the application has defined in the PWM_Config array.

You will need to check the device-specific PWM driver implementation's header file for example configuration. Please also refer to the Board.c file of any of your examples to see the PWM configuration.

Initializing the PWM Driver

PWM_init() must be called before any other PWM APIs. This function calls the device implementation's PWM initialization function, for each element of PWM_config[].

Opening the PWM Driver

Opening a PWM requires four steps:

  1. Create and initialize a PWM_Params structure.
  2. Fill in the desired parameters.
  3. Call PWM_open(), passing the index of the PWM in the PWM_config structure, and the address of the PWM_Params structure. The PWM instance is specified by the index in the PWM_config structure.
  4. Check that the PWM handle returned by PWM_open() is non-NULL, and save it. The handle will be used to read and write to the PWM you just opened.

Only one PWM index can be used at a time; calling PWM_open() a second time with the same index previously passed to PWM_open() will result in an error. You can, though, re-use the index if the instance is closed via PWM_close(). In the example code, Board_PWM0 is passed to PWM_open(). This macro is defined in the example's Board.h file.

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.

Controlling the PWM Duty Cycle

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 Duty and Period on a Running Instance

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

Implementation

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

The PWM APIs are redirected to the device specific implementations using the PWM_FxnTable pointer of the PWM_config entry. In order to use device specific functions of the PWM driver directly, link in the correct driver library for your device and include the device specific PWM driver header file (which in turn includes PWM.h). For example, for the MSP432 family of devices, you would include the following header file:

#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 enum PWM_Period_Units_ PWM_Period_Units
 PWM period unit definitions. Refer to device specific implementation if using PWM_PERIOD_COUNTS (raw PWM/Timer counts). More...
 
typedef enum PWM_Duty_Units_ PWM_Duty_Units
 PWM duty cycle unit definitions. Refer to device specific implementation if using PWM_DUTY_COUNTS (raw PWM/Timer counts). More...
 
typedef enum PWM_IdleLevel_ PWM_IdleLevel
 Idle output level when PWM is not running (stopped / not started). More...
 
typedef struct PWM_Params_ PWM_Params
 PWM Parameters. More...
 
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_Period_Units

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

§ PWM_Duty_Units

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

§ PWM_IdleLevel

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

§ PWM_Params

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

§ 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
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
handleA PWM handle returned from PWM_open().
cmdA command value defined by the driver specific implementation.
argA pointer to an optional R/W (read/write) argument that is accompanied with cmd.
Returns
A PWM_Status describing an error or success state. Negative values indicate an error occurred.
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
indexLogical instance number for the PWM indexed into the PWM_config table.
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
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
handleA PWM handle returned from PWM_open().
dutyDuty cycle in the units specified by the params used in PWM_open().
Returns
A PWM status describing an error or success. Negative values indicate an error.
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
handleA PWM handle returned from PWM_open().
periodPeriod in the units specified by the params used in PWM_open().
Returns
A PWM status describing an error or success state. Negative values indicate an error.
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
handleA PWM handle returned from PWM_open().
dutyDuty cycle in the units specified by the params used in PWM_open().
periodPeriod in the units specified by the params used in PWM_open().
Returns
A PWM status describing an error or success state. Negative values indicate an error.
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
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
handleA PWM handle returned from PWM_open().
See also
PWM_open()
PWM_start()
© Copyright 1995-2018, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale