FlexTimer Pulse Width Modulation Driver (FTM_PWM)

Detailed Description

FlexTimer Pulse Width Modulation Peripheral Driver.

Hardware background

The FTM of the S32K1xx is based on a 16 bits counter and supports: input capture, output compare, PWM and some instances include quadrature decoder.

How to use FTM driver in your application

For all operation modes (without Quadrature Decoder mode) the user need to configure ftm_user_config_t. This structure will be used for initialization (FTM_DRV_Init). The next functions used are specific for each operation mode.

PWM mode

For this mode, the user needs to configure parameters such: number of PWM channels, frequency, dead time, fault channels and duty cycle, alignment (edge or center). All this information is included in the ftm_pwm_param_t structure.

FTM_DRV_UpdatePwmChannel can be used to update duty cycles at run time. If the type of update in the duty cycle when the duty cycle can have value between 0x0 (0%) and 0x8000 (100%). If the type of update in ticks when the firstEdge and secondEdge variables can have value between 0 and ftmPeriod which is stored in the state structure.

Example:

/* The state structure of instance in the PWM mode */
ftm_state_t statePwm;
#define FTM_PWM_INSTANCE 1UL
/* Fault configuration structure */
ftm_pwm_fault_param_t PWM_FaultConfig =
{
false,
true,
5U, /* Fault filter value */
{
{
true, /* Fault channel state (Enabled/Disabled) */
false, /* Fault channel filter state (Enabled/Disabled) */
FTM_POLARITY_HIGH, /* Channel output state on fault */
},
{
false, /* Fault Channel state (Enabled/Disabled) */
false, /* Fault channel filter state (Enabled/Disabled) */
FTM_POLARITY_LOW /* Channel output state on fault */
},
{
false, /* Fault Channel state (Enabled/Disabled) */
false, /* Fault channel filter state (Enabled/Disabled) */
FTM_POLARITY_LOW /* Channel output state on fault */
},
{
false, /* Fault Channel state (Enabled/Disabled) */
false, /* Fault channel filter state (Enabled/Disabled) */
FTM_POLARITY_LOW /* Channel output state on fault */
}
}
};
/* Independent channels configuration structure for PWM */
ftm_independent_ch_param_t PWM_IndependentChannelsConfig[1] =
{
{
0U, /* HwChannelId */
FTM_POLARITY_HIGH, /* edgeMode */
0x2500U, /* uDutyCyclePercent (0-0x8000) */
false, /* External Trigger */
false,
false
}
};
/* PWM configuration for PWM */
ftm_pwm_param_t PWM_PwmConfig =
{
1U, /* Number of independent PWM channels */
0U, /* Number of combined PWM channels */
FTM_MODE_EDGE_ALIGNED_PWM, /* PWM mode */
0U, /* DeadTime Value */
FTM_DEADTIME_DIVID_BY_4, /* DeadTime clock divider */
7481U, /* PWM frequency */
PWM_IndependentChannelsConfig, /* Independent PWM channels configuration structure */
NULL, /* Combined PWM channels configuration structure */
&PWM_FaultConfig /* PWM fault configuration structure */
};
/* Timer mode configuration for PWM */
/* Global configuration of PWM */
ftm_user_config_t PWM_InitConfig =
{
{
true, /* Software trigger state */
false, /* Hardware trigger 1 state */
false, /* Hardware trigger 2 state */
false, /* Hardware trigger 3 state */
true, /* Maximum loading point state */
true, /* Min loading point state */
FTM_SYSTEM_CLOCK, /* Update mode for INVCTRL register */
FTM_SYSTEM_CLOCK, /* Update mode for SWOCTRL register */
FTM_SYSTEM_CLOCK, /* Update mode for OUTMASK register */
FTM_SYSTEM_CLOCK, /* Update mode for CNTIN register */
false, /* Auto clear trigger state for hardware trigger */
FTM_UPDATE_NOW, /* Select synchronization method */
},
FTM_MODE_EDGE_ALIGNED_PWM, /* PWM mode */
FTM_CLOCK_DIVID_BY_4, /* FTM clock pre-scaler */
FTM_CLOCK_SOURCE_SYSTEMCLK, /* FTM clock source */
FTM_BDM_MODE_11, /* FTM debug mode */
false, /* Interrupt state */
false /* Initialization trigger */
};
FTM_DRV_Init(FTM_PWM_INSTANCE, &PWM_InitConfig, &statePwm);
FTM_DRV_InitPwm(FTM_PWM_INSTANCE, &PWM_PwmConfig);
/* It's recommended to use softwareTrigger = true */
/* The SECOND_EDGE value is used only when PWM is used in combined mode */
FTM_DRV_UpdatePwmChannel(FTM_PWM_INSTANCE, 0UL, FTM_PWM_UPDATE_IN_DUTY_CYCLE, 0x800U, 0x2000U, true);

PWM in Modified Combine mode

For this mode the user needs to configure parameters such: number of PWM channels, frequency, dead time, fault channels and duty cycle, alignment (edge or center). All this information is included in ftm_pwm_param_t data type. The Modified Combine PWM mode is intended to support the generation of PWM signals where the period is not modified while the signal is being generated, but the duty cycle will be varied. FTM_DRV_UpdatePwmChannel can be used to update duty cycles at run time. If the type of update in the duty cycle when the duty cycle can have value between 0x0 (0%) and 0x8000 (100%). If the type of update in ticks when the firstEdge and secondEdge variables can have value between 0 and ftmPeriod which is stored in the state structure.In this mode, an even channel (n) and adjacent odd channel (n+1) are combined to generate a PWM signal in the channel (n) output. Thus, the channel (n) match edge is fixed and the channel (n+1) match edge can be varied.

Example:

/* The state structure of instance in the PWM mode */
ftm_state_t statePwm;
#define FTM_PWM_INSTANCE 0UL
/* Fault configuration structure */
ftm_pwm_fault_param_t PWM_FaultConfig =
{
false,
true,
5U, /* Fault filter value */
{
{
true, /* Fault channel state (Enabled/Disabled )*/
false, /* Fault channel filter state (Enabled/Disabled) */
FTM_POLARITY_HIGH, /* Channel output state on fault */
},
{
false, /* Fault Channel state (Enabled/Disabled) */
false, /* Fault channel filter state (Enabled/Disabled) */
FTM_POLARITY_LOW /* Channel output state on fault */
},
{
false, /* Fault Channel state (Enabled/Disabled) */
false, /* Fault channel filter state (Enabled/Disabled) */
FTM_POLARITY_LOW /* Channel output state on fault */
},
{
false, /* Fault Channel state (Enabled/Disabled) */
false, /* Fault channel filter state (Enabled/Disabled) */
FTM_POLARITY_LOW /* Channel output state on fault */
}
}
};
/* Combine channels configuration structure for PWM */
ftm_combined_ch_param_t flexTimer1_CombinedChannelsConfig[1] =
{
{
0U, /* Hardware channel for channel (n) */
512U, /* First edge time */
16384U, /* Second edge time */
false, /* Dead time enabled/disabled */
true, /* The modified combine mode enabled/disabled */
FTM_POLARITY_HIGH, /* Channel polarity */
true, /* Output enabled/disabled for channel (n+1) */
FTM_MAIN_DUPLICATED, /* Polarity for channel (n+1) */
false, /* External Trigger on the channel (n) */
false, /* External Trigger on the channel (n+1) */
FTM_HIGH_TRUE_PULSE, /* The selection of the channel (n) mode */
FTM_HIGH_TRUE_PULSE, /* The selection of the channel (n+1) mode */
}
};
/* PWM configuration for PWM */
ftm_pwm_param_t PWM_PwmConfig =
{
0U, /* Number of independent PWM channels */
1U, /* Number of combined PWM channels */
FTM_MODE_EDGE_ALIGNED_PWM, /* PWM mode */
0U, /* DeadTime Value */
FTM_DEADTIME_DIVID_BY_4, /* DeadTime clock divider */
7481U, /* PWM frequency */
NULL, /* Independent PWM channels configuration structure */
flexTimer1_CombinedChannelsConfig, /* Combined PWM channels configuration structure */
&PWM_FaultConfig /* PWM fault configuration structure */
};
/* Timer mode configuration for PWM */
/* Global configuration of PWM */
ftm_user_config_t PWM_InitConfig =
{
{
true, /* Software trigger state */
false, /* Hardware trigger 1 state */
false, /* Hardware trigger 2 state */
false, /* Hardware trigger 3 state */
true, /* Maximum loading point state */
true, /* Min loading point state */
FTM_SYSTEM_CLOCK, /* Update mode for INVCTRL register */
FTM_SYSTEM_CLOCK, /* Update mode for SWOCTRL register */
FTM_SYSTEM_CLOCK, /* Update mode for OUTMASK register */
FTM_SYSTEM_CLOCK, /* Update mode for CNTIN register */
false, /* Auto clear trigger state for hardware trigger */
FTM_UPDATE_NOW, /* Select synchronization method */
},
FTM_MODE_EDGE_ALIGNED_PWM, /* PWM mode */
FTM_CLOCK_DIVID_BY_4, /* FTM clock pre-scaler */
FTM_CLOCK_SOURCE_SYSTEMCLK, /* FTM clock source */
FTM_BDM_MODE_11, /* FTM debug mode */
false, /* Interrupt state */
false /* Initialization trigger */
};
FTM_DRV_Init(FTM_PWM_INSTANCE, &PWM_InitConfig, &statePwm);
FTM_DRV_InitPwm(FTM_PWM_INSTANCE, &PWM_PwmConfig);
/* It's recommended to use softwareTrigger = true */
/* The SECOND_EDGE value is used only when PWM is used in combined mode */
FTM_DRV_UpdatePwmChannel(FTM_PWM_INSTANCE, 0UL, FTM_PWM_UPDATE_IN_DUTY_CYCLE, 0x0U, 0x2000U, true);

Data Structures

struct  ftm_pwm_ch_fault_param_t
 FlexTimer driver PWM Fault channel parameters. More...
 
struct  ftm_pwm_fault_param_t
 FlexTimer driver PWM Fault parameter. More...
 
struct  ftm_independent_ch_param_t
 FlexTimer driver independent PWM parameter. More...
 
struct  ftm_combined_ch_param_t
 FlexTimer driver combined PWM parameter. More...
 
struct  ftm_pwm_param_t
 FlexTimer driver PWM parameters. More...
 

Macros

#define FTM_MAX_DUTY_CYCLE   (0x8000U)
 Maximum value for PWM duty cycle. More...
 
#define FTM_DUTY_TO_TICKS_SHIFT   (15U)
 Shift value which converts duty to ticks. More...
 

Enumerations

enum  ftm_pwm_update_option_t { FTM_PWM_UPDATE_IN_DUTY_CYCLE = 0x00U, FTM_PWM_UPDATE_IN_TICKS = 0x01U }
 FlexTimer Configure type of PWM update in the duty cycle or in ticks. More...
 
enum  ftm_polarity_t { FTM_POLARITY_LOW = 0x00U, FTM_POLARITY_HIGH = 0x01U }
 FlexTimer PWM output pulse mode, high-true or low-true on match up. More...
 
enum  ftm_second_channel_polarity_t { FTM_MAIN_INVERTED = 0x01U, FTM_MAIN_DUPLICATED = 0x00U }
 FlexTimer PWM channel (n+1) polarity for combine mode. More...
 
enum  ftm_fault_mode_t { FTM_FAULT_CONTROL_DISABLED = 0x00U, FTM_FAULT_CONTROL_MAN_EVEN = 0x01U, FTM_FAULT_CONTROL_MAN_ALL = 0x02U, FTM_FAULT_CONTROL_AUTO_ALL = 0x03U }
 FlexTimer fault control. More...
 
enum  ftm_safe_state_polarity_t { FTM_HIGH_TRUE_PULSE = 0x02U, FTM_LOW_TRUE_PULSE = 0x03U }
 Select level of the channel (n) output at the beginning. More...
 

Functions

status_t FTM_DRV_DeinitPwm (uint32_t instance)
 Stops all PWM channels . More...
 
status_t FTM_DRV_InitPwm (uint32_t instance, const ftm_pwm_param_t *param)
 Configures the duty cycle and frequency and starts outputting the PWM on all channels configured in param. More...
 
status_t FTM_DRV_UpdatePwmChannel (uint32_t instance, uint8_t channel, ftm_pwm_update_option_t typeOfUpdate, uint16_t firstEdge, uint16_t secondEdge, bool softwareTrigger)
 This function updates the waveform output in PWM mode (duty cycle and phase). More...
 
status_t FTM_DRV_FastUpdatePwmChannels (uint32_t instance, uint8_t numberOfChannels, const uint8_t *channels, const uint16_t *duty, bool softwareTrigger)
 This function will update the duty cycle of PWM output for multiple channels. More...
 
status_t FTM_DRV_UpdatePwmPeriod (uint32_t instance, ftm_pwm_update_option_t typeOfUpdate, uint32_t newValue, bool softwareTrigger)
 This function will update the new period in the frequency or in the counter value into mode register which modify the period of PWM signal on the channel output. More...
 
status_t FTM_DRV_UpdatePwmPeriodDither (uint32_t instance, uint8_t newModFracVal, bool softwareTrigger)
 This function will use in the PWM period dithering. This value is added to an internal accumulator at the end of each PWM period. The value is updated with its write buffer value according to the register synchronization. More...
 
status_t FTM_DRV_UpdatePwmEdgeChannelDither (uint32_t instance, uint8_t channel, uint8_t newMatchFracVal, bool softwareTrigger)
 This function will use in the PWM edge dithering. This value is added to the channel (n) internal accumulator at the end of each PWM period. The FRACVAL is updated with its write buffer value according to the register synchronization. The PWM edge dithering is not available when the channel in the input capture modes, and the channel in output compare modes. More...
 

Macro Definition Documentation

#define FTM_DUTY_TO_TICKS_SHIFT   (15U)

Shift value which converts duty to ticks.

Definition at line 45 of file ftm_pwm_driver.h.

#define FTM_MAX_DUTY_CYCLE   (0x8000U)

Maximum value for PWM duty cycle.

Definition at line 43 of file ftm_pwm_driver.h.

Enumeration Type Documentation

FlexTimer fault control.

Implements : ftm_fault_mode_t_Class

Enumerator
FTM_FAULT_CONTROL_DISABLED 

Fault control is disabled for all channels

FTM_FAULT_CONTROL_MAN_EVEN 

Fault control is enabled for even channels only (channels 0, 2, 4, and 6), and the selected mode is the manual fault clearing

FTM_FAULT_CONTROL_MAN_ALL 

Fault control is enabled for all channels, and the selected mode is the manual fault clearing

FTM_FAULT_CONTROL_AUTO_ALL 

Fault control is enabled for all channels, and the selected mode is the automatic fault clearing

Definition at line 87 of file ftm_pwm_driver.h.

FlexTimer PWM output pulse mode, high-true or low-true on match up.

Implements : ftm_polarity_t_Class

Enumerator
FTM_POLARITY_LOW 

When counter > CnV output signal is LOW

FTM_POLARITY_HIGH 

When counter > CnV output signal is HIGH

Definition at line 63 of file ftm_pwm_driver.h.

FlexTimer Configure type of PWM update in the duty cycle or in ticks.

Implements : ftm_pwm_update_option_t_Class

Enumerator
FTM_PWM_UPDATE_IN_DUTY_CYCLE 

The type of PWM update in the duty cycle/pulse or also use in frequency update

FTM_PWM_UPDATE_IN_TICKS 

The type of PWM update in ticks

Definition at line 52 of file ftm_pwm_driver.h.

Select level of the channel (n) output at the beginning.

Implements : ftm_safe_state_polarity_t_Class

Enumerator
FTM_HIGH_TRUE_PULSE 

Clear the channel (n) output on match, (Clear the channel (n+1) output con match in combine mode and modified combine mode)

FTM_LOW_TRUE_PULSE 

Set the channel (n) output on match, (set the channel (n+1) output on match in combine mode and modified combine mode)

Definition at line 104 of file ftm_pwm_driver.h.

FlexTimer PWM channel (n+1) polarity for combine mode.

Implements : ftm_second_channel_polarity_t_Class

Enumerator
FTM_MAIN_INVERTED 

The channel (n+1) output is the inverse of the channel (n) output

FTM_MAIN_DUPLICATED 

The channel (n+1) output is the same as the channel (n) output

Definition at line 74 of file ftm_pwm_driver.h.

Function Documentation

status_t FTM_DRV_DeinitPwm ( uint32_t  instance)

Stops all PWM channels .

Parameters
[in]instanceThe FTM peripheral instance number.
Returns
counter the current counter value

Definition at line 292 of file ftm_pwm_driver.c.

status_t FTM_DRV_FastUpdatePwmChannels ( uint32_t  instance,
uint8_t  numberOfChannels,
const uint8_t *  channels,
const uint16_t *  duty,
bool  softwareTrigger 
)

This function will update the duty cycle of PWM output for multiple channels.

Parameters
[in]instanceThe FTM peripheral instance number.
[in]numberOfChannelsThe number of channels which should be updated.
[in]channelsThe list of channels which should be updated.
[in]dutyThe list of duty cycles for selected channels.
[in]softwareTriggerIf true a software trigger is generate to update PWM parameters.
Returns
success
  • STATUS_SUCCESS : Completed successfully.
  • STATUS_ERROR : Error occurred.

Definition at line 551 of file ftm_pwm_driver.c.

status_t FTM_DRV_InitPwm ( uint32_t  instance,
const ftm_pwm_param_t param 
)

Configures the duty cycle and frequency and starts outputting the PWM on all channels configured in param.

Parameters
[in]instanceThe FTM peripheral instance number.
[in]paramFTM driver PWM parameter to configure PWM options.
Returns
success
  • STATUS_SUCCESS : Completed successfully.
  • STATUS_ERROR : Error occurred.

Definition at line 43 of file ftm_pwm_driver.c.

status_t FTM_DRV_UpdatePwmChannel ( uint32_t  instance,
uint8_t  channel,
ftm_pwm_update_option_t  typeOfUpdate,
uint16_t  firstEdge,
uint16_t  secondEdge,
bool  softwareTrigger 
)

This function updates the waveform output in PWM mode (duty cycle and phase).

Parameters
[in]instanceThe FTM peripheral instance number.
[in]channelThe channel number. In combined mode, the code finds the channel.
[in]typeOfUpdateThe type of PWM update in the duty cycle/pulse or in ticks.
[in]firstEdgeDuty cycle or first edge time for PWM mode. Can take value between 0 - FTM_MAX_DUTY_CYCLE(0 = 0% from period and FTM_MAX_DUTY_CYCLE = 100% from period) Or value in ticks for the first of the PWM mode in which can have value between 0 and ftmPeriod is stored in the state structure.
[in]secondEdgeSecond edge time - only for combined mode. Can take value between 0 - FTM_MAX_DUTY_CYCLE(0 = 0% from period and FTM_MAX_DUTY_CYCLE = 100% from period). Or value in ticks for the second of the PWM mode in which can have value between 0 and ftmPeriod is stored in the state structure.
[in]softwareTriggerIf true a software trigger is generate to update PWM parameters.
Returns
success
  • STATUS_SUCCESS : Completed successfully.
  • STATUS_ERROR : Error occurred.

Definition at line 356 of file ftm_pwm_driver.c.

status_t FTM_DRV_UpdatePwmEdgeChannelDither ( uint32_t  instance,
uint8_t  channel,
uint8_t  newMatchFracVal,
bool  softwareTrigger 
)

This function will use in the PWM edge dithering. This value is added to the channel (n) internal accumulator at the end of each PWM period. The FRACVAL is updated with its write buffer value according to the register synchronization. The PWM edge dithering is not available when the channel in the input capture modes, and the channel in output compare modes.

Parameters
[in]instanceThe FTM peripheral instance number.
[in]channelThe channel number.
[in]newMatchFracValThe channel (n) match fractional value .
[in]softwareTriggerIf true a software trigger is generate to update parameters.
Returns
success
  • STATUS_SUCCESS : Completed successfully.
  • STATUS_ERROR : Error occurred.
status_t FTM_DRV_UpdatePwmPeriod ( uint32_t  instance,
ftm_pwm_update_option_t  typeOfUpdate,
uint32_t  newValue,
bool  softwareTrigger 
)

This function will update the new period in the frequency or in the counter value into mode register which modify the period of PWM signal on the channel output.

Parameters
[in]instanceThe FTM peripheral instance number.
[in]typeOfUpdateThe type of PWM update is a period in Hz or in ticks.
  • For FTM_PWM_UPDATE_IN_DUTY_CYCLE which reuse in FTM_DRV_UpdatePwmChannel function will update in Hz.
  • For FTM_PWM_UPDATE_IN_TICKS will update in ticks.
[in]newValueThe frequency or the counter value which will select with modified value for PWM signal. If the type of update in the duty cycle, the newValue parameter must be value between 1U and maximum is the frequency of the FTM counter. If the type of update in ticks, the newValue parameter must be value between 1U and 0xFFFFU.
[in]softwareTriggerIf true a software trigger is generate to update PWM parameters.
Returns
operation status
  • STATUS_SUCCESS : Completed successfully.
  • STATUS_ERROR : Error occurred.

Definition at line 485 of file ftm_pwm_driver.c.

status_t FTM_DRV_UpdatePwmPeriodDither ( uint32_t  instance,
uint8_t  newModFracVal,
bool  softwareTrigger 
)

This function will use in the PWM period dithering. This value is added to an internal accumulator at the end of each PWM period. The value is updated with its write buffer value according to the register synchronization.

Parameters
[in]instanceThe FTM peripheral instance number.
[in]newModFracValThe modulo fractional value.
[in]softwareTriggerIf true a software trigger is generate to update parameters.
Returns
success
  • STATUS_SUCCESS : Completed successfully.
  • STATUS_ERROR : Error occurred.