![]() |
![]() |
TI-RTOS Drivers
tidrivers_full_2_20_01_10
|
PWM driver interface.
============================================================================
The PWM header file should be included in an application as follows:
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 of 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 output is always low, at 100% duty is always high).
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.
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 PWM instance. Each entry in PWM_config contains a:
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>
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(* | PWM_ControlFxn) (PWM_Handle handle, unsigned int 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(* | PWM_SetDutyFxn) (PWM_Handle handle, uint32_t dutyValue) |
A function pointer to a driver specific implementation of PWM_setDuty(). More... | |
typedef int(* | PWM_SetPeriodFxn) (PWM_Handle handle, uint32_t periodValue) |
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 | PWM_control (PWM_Handle handle, unsigned int 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 (unsigned int 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 | 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 | 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) |
#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(* PWM_ControlFxn) (PWM_Handle handle, unsigned int 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(* PWM_SetDutyFxn) (PWM_Handle handle, uint32_t dutyValue) |
A function pointer to a driver specific implementation of PWM_setDuty().
typedef int(* PWM_SetPeriodFxn) (PWM_Handle handle, uint32_t periodValue) |
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 PWM_control | ( | PWM_Handle | handle, |
unsigned int | 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 | ( | unsigned int | 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 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 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(). |