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:
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.
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).
Details for the example code above are described in the following subsections.
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:
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.
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 a PWM requires four steps:
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.
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.
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:
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>
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 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... | |
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 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).
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).
typedef enum PWM_IdleLevel_ PWM_IdleLevel |
Idle output level when PWM is not running (stopped / not started).
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().
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 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_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.
enum PWM_Period_Units_ |
enum PWM_Duty_Units_ |
enum PWM_IdleLevel_ |
void PWM_close | ( | PWM_Handle | handle | ) |
Function to close a PWM instance specified by the PWM handle.
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.
handle | A PWM handle returned from PWM_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. |
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.
index | Logical instance number for the PWM indexed into the PWM_config table. |
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.
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.
handle | A PWM handle returned from PWM_open(). |
duty | Duty cycle in the units specified by the params used in PWM_open(). |
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.
handle | A PWM handle returned from PWM_open(). |
period | Period in the units specified by the params used in PWM_open(). |
void PWM_start | ( | PWM_Handle | handle | ) |
Function to start the specified PWM handle with current settings.
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().
handle | A PWM handle returned from PWM_open(). |