Pulse Width Modulation (PWM) driver.
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).
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.
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 in units of PWM_DUTY_FRACTION to 45%.
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).
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.
Refer to the Driver's Configuration section for driver configuration information.
#include <stdint.h>
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_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... | |
#define PWM_DUTY_FRACTION_MAX ((uint32_t)~0) |
Maximum duty (100%) when configuring duty cycle as a fraction of period.
#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 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 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.
#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.
#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.
#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 struct PWM_Config_* PWM_Handle |
A handle that is returned from a PWM_open() call.
typedef void(* PWM_CloseFxn) (PWM_Handle handle) |
A function pointer to a driver specific implementation of PWM_close().
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().
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 int_fast16_t(* PWM_SetDutyFxn) (PWM_Handle handle, uint32_t duty) |
A function pointer to a driver specific implementation of PWM_setDuty().
typedef int_fast16_t(* PWM_SetPeriodFxn) (PWM_Handle handle, uint32_t period) |
A function pointer to a driver specific implementation of PWM_setPeriod().
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().
typedef void(* PWM_StartFxn) (PWM_Handle handle) |
A function pointer to a driver specific implementation of PWM_start().
typedef void(* PWM_StopFxn) (PWM_Handle handle) |
A function pointer to a driver specific implementation of PWM_stop().
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.
enum 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 |
enum 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%. See Setting PWM duty above. |
PWM_DUTY_COUNTS | Duty in timer counts |
enum PWM_IdleLevel |
void PWM_close | ( | PWM_Handle | handle | ) |
Function to close a PWM instance specified by the PWM handle.
[in] | handle | A PWM handle returned from PWM_open(). |
int_fast16_t PWM_control | ( | PWM_Handle | handle, |
uint_fast16_t | cmd, | ||
void * | arg | ||
) |
Function performs implementation specific features on a given PWM_Handle.
[in] | handle | A PWM handle returned from PWM_open(). |
[in] | cmd | A command value defined by the driver specific implementation. |
[in] | arg | A pointer to an optional R/W (read/write) argument that is accompanied with cmd. |
PWM_STATUS_SUCCESS | The control call was successful. |
PWM_STATUS_ERROR | The control call failed. |
void PWM_init | ( | void | ) |
This function initializes the PWM module.
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.
[in] | index | Logical instance number for the PWM indexed into the PWM_config table. |
[in] | params | Pointer to an parameter structure. If NULL default values are used. |
void PWM_Params_init | ( | PWM_Params * | params | ) |
Function to initialize the PWM_Params structure to default values.
[in] | params | A 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
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.
[in] | handle | A PWM handle returned from PWM_open(). |
[in] | duty | Duty cycle in the units and format specified by the params used in PWM_open(). |
PWM_STATUS_SUCCESS | The duty was set successfully. |
PWM_STATUS_ERROR | The duty was not set and remains unchanged. |
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.
[in] | handle | A PWM handle returned from PWM_open(). |
[in] | period | Period in the units specified by the params used in PWM_open(). |
PWM_STATUS_SUCCESS | The period was set successfully. |
PWM_STATUS_ERROR | The period was not set and remains unchanged. |
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.
[in] | handle | A PWM handle returned from PWM_open(). |
[in] | duty | Duty cycle in the units and format specified by the params used in PWM_open(). |
[in] | period | Period in the units specified by the params used in PWM_open(). |
PWM_STATUS_SUCCESS | The duty and period was set successfully. |
PWM_STATUS_ERROR | The duty and period was not set and remains unchanged. |
void PWM_start | ( | PWM_Handle | handle | ) |
Function to start the specified PWM handle with current settings.
[in] | handle | A PWM handle returned from PWM_open(). |
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().
[in] | handle | A PWM handle returned from PWM_open(). |