PWM Timer

Features

  • 16-bit up-counter

  • Preloadable auto-reload register

  • 16-bit programmable prescaler

  • Independent PWM generation per channel

  • Supported interrupts:

    • Counter overflow

    • Software update event

    • Channel counter overflow

    • Channel capture/compare

  • Operation modes:

    • PWM mode: Configurable duty cycle and period

    • Input capture: Edge-triggered counter capture

    • One-pulse mode: Programmable delayed pulse generation

Application Examples

SDK provides two implementation types for PWM Timer:

  • mbed Examples

    • Path: {SDK}\example\peripheral\mbed\Timer\mbed_pwm

    • Demonstrates PWM control in mbed environment

  • raw Examples

    • Path: {SDK}\example\peripheral\raw\Timer\{demo}

    • Demonstrates direct register-level PWM control

Key implementations:

Note

Check example’s README.md for supported chip information.

API

Raw API

PWMTIMER Exported Types

struct TIM_CCInitTypeDef

TIM Output Compare Init Structure Definition.

Public Members

u32 TIM_CCMode

Specifies the CC timer mode. This parameter can be a value of TIM_CCMode_PWM or TIM_CCMode_Inputcapture.

u32 TIM_CCPolarity

Specifies the polarity. This parameter can be TIM_CCPolarity_High/TIM_CCPolarity_Low. If CCx channel is configured as output: TIM_CCPolarity_High means OCx active high. TIM_CCPolarity_Low means OCx active low. If CCx channel is configured as input: TIM_CCPolarity_High means positive edge of TRGI is active for capture. TIM_CCPolarity_Low means negative edge of TRGI is active for capture.

u32 TIM_OCProtection

Output Compare value update protection. TIM_OCPreload_Enable/TIM_OCPreload_Disable. TIM_OCPreload_Enable means duty cycle will update when UEV happens if write to CCRx field in TIMx_CCRX. TIM_OCPreload_Disable means duty cycle will update immediately if write to CCRx field in TIMx_CCRX.

u32 TIM_OCPulse

Specifies the output pulse value to be loaded into the CCRx Register, which decides the duty cycle. This parameter can be a number between 0x0000 and 0xFFFF.

u32 TIM_ICPulseMode

Specifies the pulse mode of TIM with pulse capability. This parameter can be TIM_CCMode_PulseWidth or TIM_CCMode_PulseNumber.

RTL8721Dx:

Not supported.

PWMTIMER Exported Constants

TIM Capture Compare Control
/* Enable the Capture/Compare channel output. */
#define TIM_CCx_Enable ((u32)0x01000000)

/* Disable the Capture/Compare channel output. */
#define TIM_CCx_Disable ((u32)0x00000000)

/* Check if CCx enable/disable value is valid. */
#define IS_TIM_CCX (((CCX) == TIM_CCx_Enable) || ((CCX) == TIM_CCx_Disable))

/* Enable output compare preload register on CCRx. */
#define TIM_OCPreload_Enable ((u32)0x02000000)

/* Disable output compare preload register on CCRx. */
#define TIM_OCPreload_Disable ((u32)0x00000000)

/* Check if output compare preload state value is valid. */
#define IS_TIM_OCPRELOAD_STATE (((STATE) == TIM_OCPreload_Enable) || \
    ((STATE) == TIM_OCPreload_Disable))

/* if input is set : Positive edge of TRGI is active for capture */
#define TIM_CCPolarity_High ((u32)0x00000000)

/* if input is set : negative edge of TRGI is active for capture */
#define TIM_CCPolarity_Low ((u32)0x04000000)

/* Check if CC polarity value is valid. */
#define IS_TIM_CC_POLARITY (((POLARITY) == TIM_CCPolarity_High) || \
    ((POLARITY) == TIM_CCPolarity_Low))

/* CC channel configured as PWM output mode. */
#define TIM_CCMode_PWM ((u32)0x00000000)

/* CC channel configured as input capture mode. */
#define TIM_CCMode_Inputcapture ((u32)0x08000000)

/* Check if CC mode value is valid. */
#define IS_TIM_CC_MODE (((MODE) == TIM_CCMode_PWM) || \
    ((MODE) == TIM_CCMode_Inputcapture))
TIM CC Event Source
/* Event source: Capture/Compare channel 0 event. */
#define TIM_EventSource_CC0 ((u32)0x00000002)

/* Event source: Capture/Compare channel 1 event. */
#define TIM_EventSource_CC1 ((u32)0x00000004)

/* Event source: Capture/Compare channel 2 event. */
#define TIM_EventSource_CC2 ((u32)0x00000008)

/* Event source: Capture/Compare channel 3 event. */
#define TIM_EventSource_CC3 ((u32)0x00000010)
RTL8721Dx: 
/* Event source: Capture/Compare channel 4 event. */
#define TIM_EventSource_CC4 ((u32)0x00000020)

/* Event source: Capture/Compare channel 5 event. */
#define TIM_EventSource_CC5 ((u32)0x00000040)

/* Event source: Capture/Compare channel 6 event. */
#define TIM_EventSource_CC6 ((u32)0x00000080)

/* Event source: Capture/Compare channel 7 event. */
#define TIM_EventSource_CC7 ((u32)0x00000100)
TIM Channel
/* Timer channel 0 index. */
#define TIM_Channel_0 ((u16)0x0000)

/* Timer channel 1 index. */
#define TIM_Channel_1 ((u16)0x0001)

/* Timer channel 2 index. */
#define TIM_Channel_2 ((u16)0x0002)

/* Timer channel 3 index. */
#define TIM_Channel_3 ((u16)0x0003)
RTL8721Dx: 
/* Timer channel 4 index. */
#define TIM_Channel_4 ((u16)0x0004)

/* Timer channel 5 index. */
#define TIM_Channel_5 ((u16)0x0005)

/* Timer channel 6 index. */
#define TIM_Channel_6 ((u16)0x0006)

/* Timer channel 7 index. */
#define TIM_Channel_7 ((u16)0x0007)

/* Check if channel index is a valid timer channel. */
#define IS_TIM_CHANNEL (((CHANNEL) == TIM_Channel_0) || \
    ((CHANNEL) == TIM_Channel_1) || \
    ((CHANNEL) == TIM_Channel_2) || \
    ((CHANNEL) == TIM_Channel_3) || \
    ((CHANNEL) == TIM_Channel_4) || \
    ((CHANNEL) == TIM_Channel_5) || \
    ((CHANNEL) == TIM_Channel_6) || \
    ((CHANNEL) == TIM_Channel_7))
TIM Default Level
/* PWM one-pulse default output level: high. */
#define TIMPWM_DefaultLevel_High ((u32)0x00000000)

/* PWM one-pulse default output level: low. */
#define TIMPWM_DefaultLevel_Low ((u32)0x00000001)

/* Check if default level value is valid. */
#define IS_TIMPWM_DefaultLevel (((LEVEL) == TIMPWM_DefaultLevel_High) || ((LEVEL) == TIMPWM_DefaultLevel_Low))
TIM Interrupt Control
/* Timer counter update interrupt flag. */
#define TIM_IT_Update ((u32)0x00000001)

/* Capture/Compare channel 0 interrupt flag. */
#define TIM_IT_CC0 ((u32)0x00000002)

/* Capture/Compare channel 1 interrupt flag. */
#define TIM_IT_CC1 ((u32)0x00000004)

/* Capture/Compare channel 2 interrupt flag. */
#define TIM_IT_CC2 ((u32)0x00000008)

/* Capture/Compare channel 3 interrupt flag. */
#define TIM_IT_CC3 ((u32)0x00000010)

/* Channel 0 update interrupt enable flag. */
#define TIM_IT_UIE0 ((u32)0x00010000)

/* Channel 1 update interrupt enable flag. */
#define TIM_IT_UIE1 ((u32)0x00020000)

/* Channel 2 update interrupt enable flag. */
#define TIM_IT_UIE2 ((u32)0x00040000)

/* Channel 3 update interrupt enable flag. */
#define TIM_IT_UIE3 ((u32)0x00080000)
RTL8721Dx: 
/* Capture/Compare channel 4 interrupt flag. */
#define TIM_IT_CC4 ((u32)0x00000020)

/* Capture/Compare channel 5 interrupt flag. */
#define TIM_IT_CC5 ((u32)0x00000040)

/* Capture/Compare channel 6 interrupt flag. */
#define TIM_IT_CC6 ((u32)0x00000080)

/* Capture/Compare channel 7 interrupt flag. */
#define TIM_IT_CC7 ((u32)0x00000100)

/* Channel 4 update interrupt enable flag. */
#define TIM_IT_UIE4 ((u32)0x00100000)

/* Channel 5 update interrupt enable flag. */
#define TIM_IT_UIE5 ((u32)0x00200000)

/* Channel 6 update interrupt enable flag. */
#define TIM_IT_UIE6 ((u32)0x00400000)

/* Channel 7 update interrupt enable flag. */
#define TIM_IT_UIE7 ((u32)0x00800000)

/* Check if interrupt source bitmask is valid. */
#define IS_TIM_IT ((((IT) & (u32)0xFF00FE00) == 0x0000) && (((IT) & (u32)0xFF01FF) != 0x0000))

/* Check if a single interrupt source value is valid. */
#define IS_TIM_GET_IT (((IT) == TIM_IT_Update) || \
    ((IT) == TIM_IT_CC0) || \
    ((IT) == TIM_IT_CC1) || \
    ((IT) == TIM_IT_CC2) || \
    ((IT) == TIM_IT_CC3) || \
    ((IT) == TIM_IT_CC4) || \
    ((IT) == TIM_IT_CC5) || \
    ((IT) == TIM_IT_CC6) || \
    ((IT) == TIM_IT_CC7) || \
    ((IT) == TIM_IT_UIE0) || \
    ((IT) == TIM_IT_UIE1) || \
    ((IT) == TIM_IT_UIE2) || \
    ((IT) == TIM_IT_UIE3) || \
    ((IT) == TIM_IT_UIE4) || \
    ((IT) == TIM_IT_UIE5) || \
    ((IT) == TIM_IT_UIE6) || \
    ((IT) == TIM_IT_UIE7))
TIM OPM Control
/* External trigger polarity: positive edge active. */
#define TIM_OPMode_ETP_positive ((u32)0x00000000)

/* External trigger polarity: negative edge active. */
#define TIM_OPMode_ETP_negative ((u32)0x00000100)

/* External trigger polarity: both edges active. */
#define TIM_OPMode_ETP_bothedge ((u32)0x00000200)

/* Check if external trigger polarity mode is valid. */
#define IS_TIM_OPM_ETP_MODE (((MODE) == TIM_OPMode_ETP_positive) || \
    ((MODE) == TIM_OPMode_ETP_negative) || \
    ((MODE) == TIM_OPMode_ETP_bothedge))

/* One-pulse mode: counter stops at next update event. */
#define TIM_OPMode_Single ((u32)0x00000008)

/* Repetitive (PWM) mode: counter does not stop at next update event. */
#define TIM_OPMode_Repetitive ((u32)0x00000000)

/* Check if one-pulse operation mode value is valid. */
#define IS_TIM_OPM_MODE (((MODE) == TIM_OPMode_Single) || \
    ((MODE) == TIM_OPMode_Repetitive))
TIM Phase Sync Control
/* Phase sync direction: channel delays behind reference counter. */
#define TIMPWM_PSync_Delay ((u32)0x00000000)

/* Phase sync direction: channel leads ahead of reference counter. */
#define TIMPWM_PSync_Ahead ((u32)0x00000001)

/* Check if phase sync direction value is valid. */
#define IS_TIMPWM_PSync_Dir (((DIR) == TIMPWM_PSync_Delay) || ((DIR) == TIMPWM_PSync_Ahead))

/* Enable phase sync parameter preload register. */
#define TIMPWM_PSyncPreload_Enable ((u32)0x00000000)

/* Disable phase sync parameter preload register. */
#define TIMPWM_PSyncPreload_Disable ((u32)0x00000001)

/* Check if phase sync preload state value is valid. */
#define IS_TIMPWM_PPRELOAD_STATE (((STATE) == TIMPWM_PSyncPreload_Enable) || \
    ((STATE) == TIMPWM_PSyncPreload_Disable))
TIM PWM Type
RTL8721Dx: 
/* Check if peripheral is a one-pulse capable timer. */
#define IS_TIM_ONE_PULSE_TIM (((PERIPH) == TIM8) || \
    ((PERIPH) == TIM8_S))

/* Check if peripheral is a capture/compare mode timer. */
#define IS_TIM_CCM_TIM (((PERIPH) == TIM8) || \
    ((PERIPH) == TIM9) || \
    ((PERIPH) == TIM8_S) || \
    ((PERIPH) == TIM9_S))

/* Check if peripheral is a PWM output timer. */
#define IS_TIM_PWM_TIM (((PERIPH) == TIM8) || \
    ((PERIPH) == TIM8_S))
PWM AUD Channel
RTL8721Dx:

Not supported.

PWM Audio and Motor Control
RTL8721Dx:

Not supported.

PWM Audio and Motor Interrupt Control
RTL8721Dx:

Not supported.

PWMTIMER Exported Functions

Capture Compare Management Functions
void RTIM_CCRxMode(RTIM_TypeDef *TIMx, u16 TIM_Channel, u32 TIM_CCMode)

Initialize the TIMx Channel CCmode.

Parameters:

  • TIMx – The TIM peripheral with PWM output capability. See IS_TIM_PWM_TIM macro.

  • TIM_Channel – The channel need to be set mode, which can be one of the following parameters TIM Channel.

  • TIM_CCMode –

    CCx working mode which can be one of the following parameters:

    • TIM_CCMode_PWM

    • TIM_CCMode_Inputcapture

void RTIM_CCRxSet(RTIM_TypeDef *TIMx, u32 Compare, u16 TIM_Channel)

Set the TIMx Capture Compare X register value.

Parameters:

  • TIMx – The TIM peripheral with PWM output capability. See IS_TIM_PWM_TIM macro.

  • Compare – The value specifies pulsewidth, which is in the 0x00~0xFFFF range. Duty cycle = Compare / (ARR+1).

  • TIM_Channel – The channel to be set, which can be one of the following parameters TIM Channel.

Note

  • CCRx=0 will give 0% cycle pwm pulse.

  • CCRx>=TIM_Period there will be 100% pwm pulse.

void RTIM_CCStructInit(TIM_CCInitTypeDef *TIM_CCInitStruct)

Fill each TIM_CCInitStruct member with its default value.

Parameters:

  • TIM_CCInitStruct – Pointer to a TIM_CCInitTypeDef structure which will be initialized.

void RTIM_CCxCmd(RTIM_TypeDef *TIMx, u16 TIM_Channel, u32 TIM_CCx)

Enable or disable the TIM Capture Compare Channel x.

Parameters:

  • TIMx – The TIM peripheral with CCM capability. See IS_TIM_CCM_TIM macro.

  • TIM_Channel – Specifies the TIM Channel This parameter can be one of the following values TIM Channel

  • TIM_CCx –

    Specifies the TIM Channel CCxE bit new state. This parameter can be one of the following values:

    • TIM_CCx_Enable

    • TIM_CCx_Disable

void RTIM_CCxInit(RTIM_TypeDef *TIMx, TIM_CCInitTypeDef *TIM_CCInitStruct, u16 TIM_Channel)

Initialize the TIMx Channel according to the specified parameters in the TIM_CCInitStruct.

Parameters:

  • TIMx – The TIM peripheral with CCM capability. See IS_TIM_CCM_TIM macro.

  • TIM_CCInitStruct – Pointer to a TIM_CCInitTypeDef structure that contains the configuration information for the specified TIM peripheral.

  • TIM_Channel – The channel need to be initialized, which can be one of the following parameters TIM Channel

void RTIM_CCxPolarityConfig(RTIM_TypeDef *TIMx, u32 TIM_OCPolarity, u16 TIM_Channel)

Configure the TIMx channel x polarity.

Parameters:

  • TIMx – The TIM peripheral with CCM capability. See IS_TIM_CCM_TIM macro.

  • TIM_OCPolarity –

    Specifies the OCx Polarity This parameter can be one of the following values:

    • TIM_CCPolarity_High: Output Compare active high

    • TIM_CCPolarity_Low: Output Compare active low

  • TIM_Channel – Specifies the TIM Channel This parameter can be one of the following values TIM Channel

void RTIM_OCxPreloadConfig(RTIM_TypeDef *TIMx, u32 TIM_OCProtection, u16 TIM_Channel)

Enable or disable the TIMx peripheral Preload register on CCRx.

Parameters:

  • TIMx – The TIM peripheral with PWM output capability. See IS_TIM_PWM_TIM macro.

  • TIM_OCProtection –

    New state of the TIMx peripheral Preload register This parameter can be one of the following values:

    • TIM_OCPreload_Enable: value is loaded in the active register at each update event.

    • TIM_OCPreload_Disable: new value is taken in account immediately

  • TIM_Channel – The channel need to be set, which can be one of the following parameters TIM Channel

void RTIM_SetOnePulseDefaultLevel(RTIM_TypeDef *TIMx, u16 TIM_Channel, u32 DefaultLevel)

Set the TIMx’s default level in one pulse mode.

Parameters:

  • TIMx – The TIM peripheral with PWM output capability. See IS_TIM_PWM_TIM macro.

  • TIM_Channel – The channel to be set, which can be one of the following parameters TIM Channel.

  • DefaultLevel –

    Specifies the OPM Mode Default Level. This parameter can be one of the following values:

    • TIMPWM_DefaultLevel_High

    • TIMPWM_DefaultLevel_Low

Note

  • Takes effect only in PWM output mode’s One-Pulse-Mode.

  • You must select TIM_OPMode_Single if you want to set One Pulse Mode, which makes the counter stop automatically at the next UEV.

void RTIM_SetOnePulseOutputMode(RTIM_TypeDef *TIMx, u32 TIM_OPMode, u32 TriggerPolarity)

Set the TIMx’s One Pulse Mode (output one pulse PWM mode).

Parameters:

  • TIMx – The TIM peripheral with PWM output capability. See IS_TIM_PWM_TIM macro.

  • TIM_OPMode –

    Specifies the OPM Mode to be used. This parameter can be one of the following values:

    • TIM_OPMode_Single

    • TIM_OPMode_Repetitive

  • TriggerPolarity –

    Specifies the OPM Mode Trigger Polarity. This parameter can be one of the following values:

    • TIM_OPMode_ETP_positive

    • TIM_OPMode_ETP_negative

    • TIM_OPMode_ETP_bothedge

Note

You must select TIM_OPMode_Single if you want to set One Pulse Mode, which makes the counter stop automatically at the next UEV.

RTL8721Dx:

Not supported.

Phase Sync Functions
u32 RTIM_GetChannelCountx(RTIM_TypeDef *TIMx, u16 TIM_Channel)

Get the TIMx Channel Counter value.

Parameters:

  • TIMx – The TIM peripheral with PWM output capability. See IS_TIM_PWM_TIM macro.

  • TIM_Channel – Specifies the TIM Channel This parameter can be one of the following values TIM Channel

Returns:

Counter Register value.

void RTIM_PSyncxCmd(RTIM_TypeDef *TIMx, u16 TIM_Channel, u8 NewState)

Enable or disable the TIMx Phase Sync function.

Parameters:

  • TIMx – The TIM peripheral with PWM output capability. See IS_TIM_PWM_TIM macro.

  • TIM_Channel – Specifies the TIM Channel This parameter can be one of the following values TIM Channel

  • NewState – ENABLE/DISABLE.

void RTIM_PSyncxDir(RTIM_TypeDef *TIMx, u16 TIM_Channel, u8 TIM_SyncDir)

Set the TIMx Phase Sync X direction.

Parameters:

  • TIMx – The TIM peripheral with PWM output capability. See IS_TIM_PWM_TIM macro.

  • TIM_Channel – The channel to be set, which can be one of the following parameters TIM Channel.

  • TIM_SyncDir – TIMPWM_PSync_Delay/TIMPWM_PSync_Ahead

u32 RTIM_PSyncxGet(RTIM_TypeDef *TIMx, u16 TIM_Channel)

Get the TIMx Phase Sync X value.

Parameters:

  • TIMx – The TIM peripheral with PWM output capability. See IS_TIM_PWM_TIM macro.

  • TIM_Channel – The channel to be read, which can be one of the following parameters TIM Channel.

Returns:

TIMx Phase Sync X value.

void RTIM_PSyncxPreloadConfig(RTIM_TypeDef *TIMx, u16 TIM_Channel, u32 TIM_PSyncProtection)

Enable or disable the preload function of TIMx phase sync register.

Parameters:

  • TIMx – The TIM peripheral with PWM output capability. See IS_TIM_PWM_TIM macro.

  • TIM_Channel – The channel need to be set, which can be one of the following parameters TIM Channel

  • TIM_PSyncProtection –

    TIMPWM_PSyncPreload_Enable/TIMPWM_PSyncPreload_Disable

    • TIMPWM_PSyncPreload_Enable: value is loaded in the active register at each update event.

    • TIMPWM_PSyncPreload_Disable: new value is taken in account immediately

void RTIM_PSyncxSet(RTIM_TypeDef *TIMx, u16 TIM_Channel, u32 TIM_SyncPhase)

Set the TIMx Phase Sync X value.

Parameters:

  • TIMx – The TIM peripheral with PWM output capability. See IS_TIM_PWM_TIM macro.

  • TIM_Channel – The channel to be set, which can be one of the following parameters TIM Channel.

  • TIM_SyncPhase – The phase sync value compared to CNT in TIM_CNT

Note

  • TIM_SyncPhase should always smaller than ARR value

Audio and Motor Functions
RTL8721Dx:

Not supported.

Mbed API

MBED_PWM Exported Types

Structure Type
typedef struct pwmout_s pwmout_t

Typedef struct pwmout_s to pwmout_t.

MBED_PWM Exported Functions

void pwmout_free(pwmout_t *obj)

Deinitialize the PWM device of the specified channel.

Parameters:

  • obj – PWM object defined in application software.

Note

If all channels are released, PWMTIMER will also be disabled.

void pwmout_init(pwmout_t *obj, PinName pin)

Initialize PWM channel output according to the specified pin.

Parameters:

  • obj – PWM object defined in application software.

  • pin – Pin name of corresponding PWM channel to be set.

Note

  • Default period: 1638us.

  • Default pulse width: 102us.

  • Default duty cycle: 6.227%.

void pwmout_period(pwmout_t *obj, float seconds)

Set the period of the specified channel in seconds.

Parameters:

  • obj – PWM object defined in application software.

  • seconds – The period value to be set in seconds(s).

void pwmout_period_ms(pwmout_t *obj, int ms)

Set the period of the specified channel in milliseconds.

Parameters:

  • obj – PWM object defined in application software.

  • ms – The period value to be set in milliseconds(ms).

void pwmout_period_us(pwmout_t *obj, int us)

Set the period of the specified channel in microseconds.

Parameters:

  • obj – PWM object defined in application software.

  • us – The period value to be set in microseconds(us).

void pwmout_pulsewidth(pwmout_t *obj, float seconds)

Set the pulse width of the specified channel in seconds.

Parameters:

  • obj – PWM object defined in application software.

  • seconds – The pulse width value to be set in seconds(s).

void pwmout_pulsewidth_ms(pwmout_t *obj, int ms)

Set the pulse width of the specified channel in milliseconds.

Parameters:

  • obj – PWM object defined in application software.

  • ms – The pulse width value to be set in milliseconds(ms).

void pwmout_pulsewidth_us(pwmout_t *obj, int us)

Set the pulse width of the specified channel in microseconds.

Parameters:

  • obj – PWM object defined in application software.

  • us – The pulse width value to be set in microseconds(us).

float pwmout_read(pwmout_t *obj)

Get the duty cycle of the specified channel.

Parameters:

  • obj – PWM object defined in application software.

Returns:

Duty cycle of the specified channel, in the range [0.0, 1.0].

void pwmout_set_polarity(pwmout_t *obj, int polarity)

Set the polarity of the specified PWM channel.

Parameters:

  • obj – PWM object defined in application software.

  • polarity –

    This parameter can be one of the following values:

    • 0: Output is LOW when timer count < set value.

    • 1: Output is HIGH when timer count < set value (default).

Attention

Configure polarity after setting duty cycle or pulse width.

void pwmout_start(pwmout_t *obj)

Enable the specified channel to output PWM.

Parameters:

  • obj – PWM object defined in application software.

void pwmout_stop(pwmout_t *obj)

Disable the specified channel to output PWM.

Parameters:

  • obj – PWM object defined in application software.

void pwmout_write(pwmout_t *obj, float percent)

Set the duty cycle of the specified channel.

Parameters:

  • obj – PWM object defined in application software.

  • percent – The duty cycle value to be set.